AMBARI-10504 - Views : create example view for Cluster Association and Auto Create (tbeerbower)

ambari-views/examples/cluster-view/docs/index.md

@@ -0,0 +1,175 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+Cluster View Example
+======
+
+Description
+-----
+The Cluster View is an example of a basic REST service that serves the configuration parameter values.
+It demonstrates the basics of view / cluster association and cluster configuration for view instances.
+It also shows how to auto-create an instance of a view and automatically associate it with a cluster.
+
+Package
+-----
+All views are packaged as a view archive. The view archive contains the configuration
+file and various optional components of the view.
+
+###view.xml
+
+The view.xml file is the only required file for a view archive.  The view.xml is the configuration that describes the view and view instances for Ambari.
+
+Note the following in the view.xml for the CLUSTER view:
+
+#####cluster-config
+
+Some of the parameter elements in the view.xml are created with a cluster-config element.
+
+    <parameter>
+      <name>hdfs_user</name>
+      <description>The hdfs_user value from the hadoop-env configuration.  Requires cluster association.</description>
+      <label>HDFS User</label>
+      <default-value>not available</default-value>
+      <cluster-config>hadoop-env/hdfs_user</cluster-config>
+    </parameter>
+
+Including a cluster-config element means that the value for the parameter's property will be acquired from cluster configuration if the view instance is associated with a cluster.  
+In this example, if an instance of this view is associated with a cluster then the value returned for the 'hdfs_user' property will come from the cluster's 'hadoop-env/hdfs_user' configuration. 
+
+#####auto-instance
+
+The view.xml contains an auto-instance element.
+
+    <auto-instance>
+      <name>AUTO_INSTANCE</name>
+      <label>Auto Create instance for the CLUSTER view</label>
+      <description>This view instance is auto created when the HDFS service is added to a cluster.</description>
+      <property>
+        <key>setting1</key>
+        <value>value1</value>
+      </property>
+      <property>
+        <key>setting2</key>
+        <value>value2</value>
+      </property>
+      <stack-id>HDP-2.*</stack-id>
+      <services>
+        <service>HDFS</service>
+      </services>
+    </auto-instance>
+    
+The auto-instance element describes an instance of the view that will be automatically created when the matching services are added to a cluster with a matching stack id.  
+In this example, an instance of the cluster view will be created when the HDFS service is added to a HDP-2.* cluster.    
+
+Build
+-----
+
+The view can be built as a maven project.
+
+    cd ambari-views/examples/cluster-view
+    mvn clean package
+
+The build will produce the view archive.
+
+    ambari-views/examples/cluster-view/target/cluster-view-???.jar
+
+Deploy
+------
+
+Place the view archive on the Ambari Server and start to deploy.    
+
+    cp cluster-view-???.jar /var/lib/ambari-server/resources/views/
+    ambari-server start
+    
+
+View Instances
+-----
+
+When you first start Ambari, you should see an instance of the CLUSTER view named INSTANCE_1.  The instance is defined in the view.xml and is created unconditionally when the view is first deployed.
+
+Access the view instance end point:
+
+    api/v1/views/CLUSTER/versions/0.1.0/instances/INSTANCE_1
+
+Access the view UI:
+
+    /views/CLUSTER/0.1.0/INSTANCE_1
+
+At this point, the instance is not associated with any cluster so accessing the view properties from within the view code should show the default value of 'not available' for the cluster-config properties.
+
+    api/v1/views/CLUSTER/versions/0.1.0/instances/INSTANCE_1/resources/configurations
+    
+    [{"hdfs_user" : "not available"}, {"proxyuser_group" : "not available"}]
+
+Cluster Association
+-----
+
+To associate a view instance with a cluster, you need to have an Ambari managed cluster.  Use the Ambari install wizard to create a cluster that includes the HDFS service.
+
+When the HDFS service is added to the cluster a new instance of the CLUSTER view named AUTO_INSTANCE should be automatically added.
+ 
+Access the view instance end point:
+     
+     api/v1/views/CLUSTER/versions/0.1.0/instances/AUTO_INSTANCE
+     
+Note that the view instance is associated with the cluster "c1" through the property 'ViewInstanceInfo/cluster_handle'.
+     
+     {
+       "href" : "http://...:8080/api/v1/views/CLUSTER/versions/0.1.0/instances/AUTO_INSTANCE",
+       "ViewInstanceInfo" : {
+         "cluster_handle" : "c1",
+         "context_path" : "/views/CLUSTER/0.1.0/AUTO_INSTANCE",
+         "description" : "This view instance is auto created when the HDFS services are added to a cluster.",
+         "icon64_path" : null,
+         "icon_path" : null,
+         "instance_name" : "AUTO_INSTANCE",
+         "label" : "Auto Create instance for the CLUSTER view",
+         "static" : false,
+         "version" : "0.1.0",
+         "view_name" : "CLUSTER",
+         "visible" : true,
+         "instance_data" : { },
+         "properties" : {
+           "hdfs_user" : "not available",
+           "proxyuser_group" : "not available",
+           "setting1" : "value1",
+           "setting2" : "value2"
+         }
+       }, ...
+       
+Access the view UI:
+
+    /views/CLUSTER/0.1.0/AUTO_INSTANCE
+           
+You should be able to use the view UI or the API to see the values of the configuration properties.
+
+    api/v1/views/CLUSTER/versions/0.1.0/instances/AUTO_INSTANCE/resources/configurations
+           
+    [{"hdfs_user" : "hdfs"}, {"proxyuser_group" : "users"}]
+           
+The values of the properties should match what is in the actual cluster configuration.
+
+To associate the view instance INSTANCE_1 with the cluster, you should set the 'ViewInstanceInfo/cluster_handle' property.
+ 
+    PUT /api/v1/views/CLUSTER/versions/0.1.0/instances/INSTANCE_1
+        {
+          "ViewInstanceInfo" : {
+            "cluster_handle" : "c1"
+          }
+        }
+Once the view is associated with the cluster, you should see the actual configuration values through the view UI.
+        
+        
+           

ambari-views/examples/cluster-view/pom.xml

@@ -0,0 +1,84 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <parent>
+    <groupId>org.apache.ambari</groupId>
+    <artifactId>ambari-view-examples</artifactId>
+    <version>2.0.0-SNAPSHOT</version>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+  <artifactId>cluster-view</artifactId>
+  <version>2.0.0-SNAPSHOT</version>
+  <packaging>jar</packaging>
+  <name>Ambari Cluster View</name>
+  <url>http://maven.apache.org</url>
+  <properties>
+    <ambari.dir>${project.parent.parent.parent.basedir}</ambari.dir>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.ambari</groupId>
+      <artifactId>ambari-views</artifactId>
+      <version>[1.7.0.0,)</version>
+    </dependency>
+    <dependency>
+      <groupId>com.sun.jersey</groupId>
+      <artifactId>jersey-server</artifactId>
+      <version>1.8</version>
+    </dependency>
+    <dependency>
+      <groupId>javax.inject</groupId>
+      <artifactId>javax.inject</artifactId>
+      <version>1</version>
+    </dependency>
+    <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>servlet-api</artifactId>
+      <version>2.5</version>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <version>2.12</version>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+    <plugins>
+        <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>rpm-maven-plugin</artifactId>
+        <version>2.0.1</version>
+        <executions>
+          <execution>
+            <phase>none</phase>
+            <goals>
+              <goal>rpm</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

ambari-views/examples/cluster-view/src/main/java/org/apache/ambari/view/cluster/ClusterConfigServlet.java

@@ -0,0 +1,65 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.ambari.view.cluster;
+
+import org.apache.ambari.view.ViewContext;
+
+import javax.servlet.ServletConfig;
+import javax.servlet.ServletContext;
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.util.Map;
+
+/**
+ * Simple servlet for cluster view.
+ */
+public class ClusterConfigServlet extends HttpServlet {
+
+  /**
+   * The view context.
+   */
+  private ViewContext viewContext;
+
+  @Override
+  public void init(ServletConfig config) throws ServletException {
+    super.init(config);
+
+    ServletContext context = config.getServletContext();
+    viewContext = (ViewContext) context.getAttribute(ViewContext.CONTEXT_ATTRIBUTE);
+  }
+
+  @Override
+  protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
+    response.setContentType("text/html");
+    response.setStatus(HttpServletResponse.SC_OK);
+
+    PrintWriter writer = response.getWriter();
+
+    Map<String, String> properties = viewContext.getProperties();
+
+    writer.println("<h1>Cluster Configurations</h1>");
+    writer.println("</br>hdfs_user       = " + properties.get("hdfs_user"));
+    writer.println("</br>proxyuser_group = " + properties.get("proxyuser_group"));
+  }
+}
+

ambari-views/examples/cluster-view/src/main/java/org/apache/ambari/view/cluster/ClusterConfigurationService.java

@@ -0,0 +1,47 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.ambari.view.cluster;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.HttpHeaders;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
+
+/**
+ * The cluster configuration service.
+ */
+public class ClusterConfigurationService extends PropertyService {
+
+  /**
+   * Handles: GET /.
+   *
+   * @param headers   http headers
+   * @param ui        uri info
+   *
+   * @return value JSON representation
+   */
+  @GET
+  @Path("/")
+  @Produces({"text/plain", "application/json"})
+  public Response getValue(@Context HttpHeaders headers, @Context UriInfo ui) {
+    return Response.ok(getResponse("hdfs_user", "proxyuser_group")).build();
+  }
+} // end PropertyService

ambari-views/examples/cluster-view/src/main/java/org/apache/ambari/view/cluster/PropertyService.java

@@ -0,0 +1,68 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.ambari.view.cluster;
+
+import org.apache.ambari.view.ViewContext;
+
+import javax.inject.Inject;
+import java.util.Map;
+
+/**
+ * The base property service.
+ */
+public abstract class PropertyService {
+
+  /**
+   * The view context.
+   */
+  @Inject
+  protected ViewContext context;
+
+  protected String getResponse(String ... propertyNames) {
+
+    Map<String, String> properties = context.getProperties();
+
+    StringBuffer buffer = new StringBuffer();
+    int count = 0;
+
+    buffer.append("[");
+    for (String propertyName : propertyNames) {
+      if (count++ > 0) {
+        buffer.append(",\n");
+      }
+      buffer.append(getPropertyResponse(properties, propertyName));
+    }
+    buffer.append("]");
+
+    return buffer.toString();
+  }
+
+  private String getPropertyResponse(Map<String, String> properties, String key) {
+    StringBuffer buffer = new StringBuffer();
+
+    String value = properties.get(key);
+
+    buffer.append("{\"");
+    buffer.append(key);
+    buffer.append("\" : \"");
+    buffer.append(value);
+    buffer.append("\"}");
+
+    return buffer.toString();
+  }
+} // end PropertyService

ambari-views/examples/cluster-view/src/main/java/org/apache/ambari/view/cluster/SettingService.java

@@ -0,0 +1,47 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.ambari.view.cluster;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.HttpHeaders;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
+
+/**
+ * The setting service.
+ */
+public class SettingService extends PropertyService {
+
+  /**
+   * Handles: GET /.
+   *
+   * @param headers   http headers
+   * @param ui        uri info
+   *
+   * @return value JSON representation
+   */
+  @GET
+  @Path("/")
+  @Produces({"text/plain", "application/json"})
+  public Response getValue(@Context HttpHeaders headers, @Context UriInfo ui) {
+    return Response.ok(getResponse("setting1", "setting2")).build();
+  }
+} // end PropertyService

ambari-views/examples/cluster-view/src/main/resources/WEB-INF/web.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License. Kerberos, LDAP, Custom. Binary/Htt
+-->
+
+<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+         version="2.4">
+
+  <display-name>Cluster Application</display-name>
+  <description>
+    This is the cluster view application.
+  </description>
+  <servlet>
+    <servlet-name>ClusterConfigServlet</servlet-name>
+    <servlet-class>org.apache.ambari.view.cluster.ClusterConfigServlet</servlet-class>
+  </servlet>
+  <servlet-mapping>
+    <servlet-name>ClusterConfigServlet</servlet-name>
+    <url-pattern>/</url-pattern>
+  </servlet-mapping>
+</web-app>

ambari-views/examples/cluster-view/src/main/resources/view.xml

@@ -0,0 +1,90 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<view>
+  <name>CLUSTER</name>
+  <label>Cluster View</label>
+  <version>0.1.0</version>
+  <description>View to demonstrate cluster association and auto instance creation.</description>
+  <parameter>
+    <name>setting1</name>
+    <description>The first setting.</description>
+    <label>Setting #1</label>
+    <placeholder>placeholder text for the first setting</placeholder>
+    <default-value>default value 1</default-value>
+    <required>true</required>
+  </parameter>
+  <parameter>
+    <name>setting2</name>
+    <description>The second setting.</description>
+    <label>Setting #2</label>
+    <placeholder>placeholder text for the second setting</placeholder>
+    <default-value>default value 2</default-value>
+    <required>true</required>
+  </parameter>
+  <parameter>
+    <name>hdfs_user</name>
+    <description>The hdfs_user value from the hadoop-env configuration.  Requires cluster association.</description>
+    <label>HDFS User</label>
+    <default-value>not available</default-value>
+    <cluster-config>hadoop-env/hdfs_user</cluster-config>
+  </parameter>
+  <parameter>
+    <name>proxyuser_group</name>
+    <description>The proxyuser_group value from the hadoop-env configuration.  Requires cluster association.</description>
+    <label>ProxyUser Group</label>
+    <default-value>not available</default-value>
+    <cluster-config>hadoop-env/proxyuser_group</cluster-config>
+  </parameter>
+  <resource>
+    <name>configurations</name>
+    <service-class>org.apache.ambari.view.cluster.ClusterConfigurationService</service-class>
+  </resource>
+  <resource>
+    <name>settings</name>
+    <service-class>org.apache.ambari.view.cluster.SettingService</service-class>
+  </resource>
+  <auto-instance>
+    <name>AUTO_INSTANCE</name>
+    <label>Auto Create instance for the CLUSTER view</label>
+    <description>This view instance is auto created when the HDFS service is added to a cluster.</description>
+    <property>
+      <key>setting1</key>
+      <value>value1</value>
+    </property>
+    <property>
+      <key>setting2</key>
+      <value>value2</value>
+    </property>
+    <stack-id>HDP-2.*</stack-id>
+    <services>
+      <service>HDFS</service>
+    </services>
+  </auto-instance>
+  <instance>
+    <name>INSTANCE_1</name>
+    <label>Default instance for the CLUSTER view</label>
+    <description>This view instance is created when the CLUSTER view is deployed.  The instance must be associated with a cluster to have valid cluster configuration values.</description>
+    <property>
+      <key>setting1</key>
+      <value>value1</value>
+    </property>
+    <property>
+      <key>setting2</key>
+      <value>value2</value>
+    </property>
+  </instance>
+</view>

ambari-views/examples/pom.xml

@@ -34,6 +34,7 @@
     <module>favorite-view</module>
     <module>phone-list-view</module>
     <module>calculator-view</module>
+    <module>cluster-view</module>
     <module>weather-view</module>
     <module>restricted-view</module>
     <module>simple-view</module>