- 1.0 Introduction
- 2.0 Target Audience
- 3.0 System Requirements
- 4.0 Developing Custom Portlets with Java
- 4.1 Introduction to the Java Client for the Collage REST API
- 4.2 Introduction to the Portlet API
- 4.3 Overview of the Tutorial Project
- 4.4 The Hosts Portlet Tutorial
- 6.0 Deployment
GroundWork Monitor 7, is an industry leading open platform for unified monitoring. The GroundWork user interface is a modern web portal built upon a foundation of standard, open source tools and frameworks.
To summarize, you will learn:
- About the Collage REST API and how to use this API to retrieve and display monitoring data
- How to develop a Java Portlet with server-side Java code, as well JSP and JSTL
- How to deploy your portlets to the GroundWork Monitor server
Requirements for building, deploying and running the examples:
- Java 7 JDK
- Maven 3 (preferable 3.2.1 or higher)
- GroundWork Monitor Portal 7.0.2
Our first example is a pure Java solution. This solution will use the Java REST API Client to retrieve monitoring data.
REST (REpresentational State Transfer) is a distributed computing style based on the architectural successes of the web. The Collage REST API for GroundWork Monitor is a set of distributed web service APIs adhering to the design principles of REST. A Java Client is provided with the tutorial project. The REST API from Java is very easy to use.
This Java Client will return results as Data Transfer Objects (DTOs). These DTOs are simple, serializable Java beans. All entities in the GroundWork Monitor model are accessible via the Java Client. Here are some examples of using the HostClient:
Additionally, there are both Business/Bulk APIs and CRUD operations for inserting, updating and deleting GroundWork entities not covered in this tutorial. A brief list of APIs include:
- Host Groups, Service Groups, Custom Groups
- Performance Data
- Device Templates
To learn more about the GroundWork REST API, see the online documentation: RESTful API Documentation
The Portlet interface is used by a Java portal to invoke portlets. Every portlet has to implement this interface, either by directly implementing it, or by using an existing class implementing the Portlet interface.
A portlet is a Java technology-based web component. It is managed by the portal and processes requests and generates dynamic content as response. Portlets are used by portals as pluggable user interface components.
The portal instantiates portlets, manages their life-cycle and invokes them to process requests. The life-cycle consists of:
- Initializing the portlet using the init method
- Request processing
- Processing actions
- Taking the portlet out of service using the destroy method
We will covering two of these phase in our portlet examples: Request processing and Processing actions
The Tutorial is zipped up and can be downloaded from here: gw-portlet-examples.zip
This project is built with the industry standard Maven open source build tool. To build the application, type:
This command should complete with the message "BUILD SUCCESSFUL". The build creates a Java web application (WAR) file. WAR files are packaged in a standard way so that they can be deployed to any Java application server. Look in the target directory, the war file can be found there:
First, lets look at the pom.xml file found in the root of your project. This file contains the declarative Maven build instructions. All of the project dependencies on third-party Java libraries are listed here, for example:
All of these dependencies are downloaded over the internet. Besides the standard internet locations, we've added several other remote repositories including GroundWork repositories:
You will deploy this file to the GroundWork server in the Deployment section at the end of this document.
Open up the tutorial project in your favorite IDE such as Eclipse or IntelliJ. In this tutorial, we are going to work with a portlet which shows a list of all Hosts in the system in an HTML table. Each row in the table will have a hyperlink to the services for the given host. When the user clicks on that link, a second page is displayed with all services listed for the select host.
In this lesson, we will work with one Java class and JSP files:
Additionally, we will be using:
- The Collage REST API Client Library for retrieving monitoring data from the GroundWork server
- Data Transfer Object classes, which are simple serializable bean classes, will be returned by the Collage REST API Client Library
In HostsTutorialPortlet.java, we are using GroundWork REST API to get a list of all hosts in the system. The list is retrieved in the portlet's doView method and prepared for rendering on a browser. The doView method is called by the portal whenever the portlet is rendered on the page. Here is the doView method:
The doView method is the standard entry point to rendering a portlet. This interface is defined by the Portlet API. A RenderRequest and RenderResponse object is passed into the portlet. The request holds all HTTP information about the requesting being made, such as request parameters and HTTP headers. The response is where you write your web content to, usually by including a JSP template or similar technology.
All REST API clients must authenticate to GroundWork. We provide the plumbing for authenticating in the provided base class (DashboardPortlet.java). You just have to make sure that your /usr/local/groundwork/config/ws_client.properties has the correct username, password, and end point:
If you fail to authenticate, the base class will display a message to the portlet output. You should not render your portlet if authentication fails.
Passing Attributes to View
Here is how you make Java objects visible in your JSP:
The setAttribute method on the Portlet request makes Java objects easily accessible in your JSP template. In this case, we have taken the result of the retrieveHosts() method, which is a List of DtoHost plain old Java objects. We'll see how easy it is to access these objects in a JSP template in the next section.
Dispatching to a JSP
The Portlet API provides standard methods for including the merged content of a JSP into your portlet. Commonly, you will you use request dispatchers. You will want to use the include method of the dispatcher:
Portlets should generate their HTML using a template language. In our example, we use the JSP template language for creating our dynamic HTML content. Open up the hosts-tutorial.jsp file in your editor. We skip the boiler-plate code and get down to how we generate our table of hosts:
The forEach tag is a Java JSTL tag for iterating of Java collections such as the List of DtoHosts we added in the doView, by setting an attribute named "hosts". You can see this variable accessed here in our JSP template:
For each host in the collection, we iterate over the list, effecting creating a table row for each host in the list:
Note that you simply use dot notation to retrieve values from the DtoHost object. GroundWork dynamic properties can also be retrieved with the getProperty() method. Notice that the host name has some special processing:
Here we use a Portlet API tag to create an Action URL linking back to our portlet. Additionally, the hostName is passed in as a standard portlet request parameter. Next, lets look at what happens when this link is clicked on...
Portlet Actions are how you handle HTTP actions such as form submits. In this example, we show how to process the action generated by the actionURL tag in the previous section. Actions are executed in the Portlet API processAction method:
First thing we do here is retrieve the hostName that was set on the actionURL tag in the JSP above.
With this hostName, we retrieve all the services for the given host and pass the list of host names to the doView method by publishing a portlet message:
The doView method then consumes the message passed to it in the doView method:
Lets take a closer look at how we retrieve hosts and services...
Hosts and Services are retrieved using the GroundWork REST API. Java clients are provided to greatly simplify the usage. The Java clients have a robust interface including CRUD and Query operations. Here we retrieve all hosts:
And for services, we retrieve all services for a given host:
The DtoHost and DtoService objects are plain old java objects (serializable and safe for the java session) containing all attributes of a host or service.
The Portlet API provides a standard way of storing portlet data, known as preferences. These preferences are persistent and can be stored on a per user basis. Going back to doView method, you can see where we retrieve a single preference named "rows". This preference holds the number of rows to display on a page. Although this simple example does not make use of the rows preference, this gives you an idea of how you can customize the view of a portlet on a per user basis:
Allowed preferences for a portlet are defined in the portlet.xml descriptor. In fact, all portlets much be defined in the portlet.xml deployment descriptor.
The portlet.xml file, found in src/main/webapp/WEB-INF/portlet.xml, holds definitions of all portlets in this application. It tells the portal about the portlets being deployed in this application. Notice that there is a section for preferences, where we define the rows preference default value. This default value is can be overridden per user.
(This section to be delivered soon.)
Next, we will deploy our war file that we built in the Build section to the GroundWork Portal.
Deploying the war file requires the commands:
To ensure your war file was deployed, there should be a marker file denoted that the deployment went safely:
If it failed to deploy, you will see a failed marker file
To un-deploy the war file you will need to remove any instances from the portal. Using the root login run the following commands:
|This will log out all portal users.|
Watch the video below to learn how to deploy a portlet to the GroundWork Portal and add it to the site menu. In this video, we will:
- Update the Portal Registry
- Create a new menu option on our site under Dashboards menu called "Tutorial"
- Create a new page and attach it to the menu
- Place the HostsTutorialPortlet on the page