Rogue Wave JViews TGO Sample: JSF Integration - Equipment Viewer

Description

This sample shows how to use both the network and equipment components together on a Faces application.

How to Use the Sample

The Network view is used to select a network element containing an equipment object to be displayed. There is no contextual menu configured for this view.
On the Equipment view the contextual menu (right click) can be used for several operations:
- Managing the alarm state of selected objects in the Equipment view
- Enabling or disabling interaction of different types: selection, zooming and panning
- Zooming in or out; or showing all objects in the view
The toolbar can be used for operations, such as:
- Enabling or disabling interaction of different types in both the Network and Equipment views: selection, zooming and panning
- Zooming in or out; or showing all objects in both the Network and Equipment views
The message box shows messages that provide information to users on the name of an interactor when hovered the buttons in the toolbar.
The overview can be used to select the region being viewed in the Network view
The selection panel shows the currently selected object of the Network and Equipmetn view, if any

Installing the Thin-Client Sample

The sample contains a WAR file (Web Archive) that allows you to easily install the sample on any server that supports the Servlet API 2.1 or later. For your convenience, the WAR will be copied to the Tomcat web server that is supplied with the Rogue Wave JViews installation when you start the server using the supplied scripts. Tomcat is the official reference implementation of the Servlet and JSP specifications. If you are already using an up-to-date Web or application server, there is a good chance that it already has everything you need. The sample can also be deployed to WebSphere Application Server (WAS).

Running the Sample Using Tomcat

If you intend to use the Tomcat Web server provided with this installation, follow these instructions to start the server: Running the Server-Side Samples. The scripts to start the server can be found in the tools/tomcat-jsf directory.
Note: if you are running on Windows then you will find menu items in the Windows "start" menu to start and stop the Tomcat server.

Once the server is running, you can see the sample by opening the following page:

Rogue Wave JViews TGO Sample: JSF Integration - Equipment Viewer
http://localhost:8080/jsf-integration-equipment-viewer

Running the Sample Using WebSphere Application Server

In addition to the instructions provided for using Tomcat, the samples can be viewed on WebSphere Application Server. Follow the instructions: Running the Server-Side Samples and use the scripts to start the server and deploy the sample.

Once the server is running, you can see the sample by opening the following page: http://localhost:9443/jsf-integration-equipment-viewer
The WAS administrative console can be used to verify or modify server settings: http://localhost:9043/ibm/console/

Note: the WAS server can start on a range of port numbers, therefore the value is not guaranteed to remain the same. The scripts provided with the samples can be used to obtain the port numbers used by the Admin Console and by the deployed Web applications. To retrieve a list of all the WAS port numbers, run the command line instruction: ant -f build_was.xml ws.list.ports

Topics Covered

Use of realistic images as the equipment and business objects
Sharing the same business objects between both components
JViews TGO Faces Equipment View Component
JViews TGO Faces Network View Component
JViews TGO Faces Client Select Interactor
JViews Framework Faces Overview within JViews TGO
JViews Framework Faces Contextual Menu within JViews TGO
Integration of Client Actions in the Contextual Menu
Integration of Server and Client Actions at once in the Contextual Menu
Integration of JavaScript code with the Client Select Interactor method bindings
JViews Framework Faces Interactors within JViews TGO
JViews Framework Faces Image Button within JViews TGO
JViews Framework Faces Message Box within JViews TGO
JViews Framework Faces Contextual Control
Styling Customization of JViews Framework and TGO Faces Components

Detailed Description

This sample shows how to use both the network and equipment components together on a Faces application, by illustrating how to:

Share the same business objects between both components to minimize redundancy at the datasource level
Associate contextual menu entries with actions in the:
- Client
- Server
- Both Server and Client (at the same time)
Enable interaction between both Network and Equipment views
Support multiple browser pages by storing contextual data per page

It is important to understand that this sample re-uses the code provided in the standard AbstractSampleContext that is used in the other JViews TGO Faces samples in a standalone class, namely the SampleContext. This SampleContext emcopasses in one file the same design and functionality as the standard AbstractSampleContext, see the SampleContext description below for more details.
So in the same manner as the AbstractSampleContext, the SampleContext serves as:

A context holding the beans needed by this sample
The abstraction in charge of initializing the sample for execution

So before proceeding it is recommended that you review the section Common Features of Faces Samples in the JViews TGO documentation to ensure that you understand the design behind the sample, see Starting the samples as this section contains more details on how the JViews TGO JSF samples are designed around the AbstractSampleContext, which despite not directly subclassing from it, is (as noted above) the underlying code base for this sample.

This sample uses the following types:

SampleContext
This standalone class augments the standard AbstractSampleContext code base by:
- Allowing for the initialization of multiple IlpGraphicComponents namely an IlpNetwork in the createNetwork and an IlpEquipment in the createEquipment method
- Creates a common IlpDefaultDataSource that is shared accross both IlpGraphicComponents
- Uses page identifier to store these contextual specific data into the session
It performs the following tasks:
- Initializes this JViews TGO runtime with the custom settings defined in the settings.css file located in webpages/resources/settings which contains the customizations needed to use the custom ports, LEDs and cards that are displayed in the Equipment view that use the real equipment images
- When needed, creates and populates the IlpDefaultDataSource that is used by both IlpNetwork and IlpEquipment
- When needed, initializes its IlpNetwork with:
  - The appropriate TGO object types that are to be visible in the Network view via theIlpNetwork's adapter's ilog.cpl.datasource.IlpAbstractHierarchyAdapter.setAcceptedClasses method, namely the IltNetworkElement and IltLink TGO types are to be visible
  - The appropriate style sheets network.css located in webpages/resources/styles/network
  - The shared IlpDefaultDataSource
- When needed, initializes its IlpEquipment with:
  - An empty List of origins that ensure that at startup the Equipment view is empty
  - The appropriate style sheets network.css located in webpages/resources/styles/equipment
  - The shared IlpDefaultDataSource
Once created, the IlpNetwork, IlpEquipment and IlpDefaultDataSource must be stored in the session using a key that combines a name and the page identifier, which is unique to the page that has submitted the request. This ensures that multiple browser pages do not share any data.
action.AlarmStateActionListener
This is the implementation that handles the management of alarm changes in the TGO object state when triggered by the contextual menu in the Equipment view
action.EquipmentVisibilityHandler
This is a bean-like type that provides the functionality necessary to manage the visibility of equipments in the Equipment view. It provides the ability to show and hide equipments via its equipmentVisibility method which is bound to the objectActionMethodBinding tag attribute of the clientSelectInteractor attached to the Network view. This bean is also responsible for identifying the currently selected objects and the currently active view
action.ServerClientActionListener
This is the implementation that is used to handle the composite Client-Post-Server action. The action.ServerClientActionListener allows individuals to specify a server side action in the form of a JSF method binding expression ("#{bean.methodName}") and a client action to be executed in the form of a JavaScript code segment. The action.ServerClientActionListener enforces that the client action is executed after the completion of the execution of the server action
popup.PopupMenuFactory
This is ilog.views.util.servlet.IlvMenuFactory implementation that populates the contextual menu for the IlpNetwork and for the IlpEquipment when right clicked. It populates the contextual menu with ilog.views.util.servlet.model.IlvMenuItems that hold ilog.views.util.servlet.event.ActionListeners of different types depending on the execution environment of interest. For example, for client-only execution, ilog.views.util.servlet.event.JavaScriptActionListener are used; and for Client-Post-Server actions action.ServerClientActionListener are used
renderer.CardBaseRendererFactory
This is the ilog.tgo.graphic.renderer.IltCardDirectImageBaseRendererFactory implementation that provides an ilog.tgo.graphic.renderer.IltBaseRenderer implementation that is used to render the custom card types. This implementation, renderer.CardBaseRendererFactory.CardBaseRenderer extends the ilog.tgo.graphic.renderer.IltCardDirectImageBaseRendererFactory.BaseRenderer in that it draws additional borders for objects that are selected
renderer.PortBaseRendererFactory
This is the ilog.tgo.graphic.renderer.IltPortDirectImageBaseRendererFactory implementation that provides an ilog.tgo.graphic.renderer.IltBaseRenderer implementation that is used to render the custom port types. This implementation, renderer.PortBaseRendererFactory.PortBaseRenderer extends the ilog.tgo.graphic.renderer.IltPortDirectImageBaseRendererFactory.BaseRenderer in that it draws additional borders for objects that are selected
renderer.LedBaseRendererFactory
This is the ilog.tgo.graphic.renderer.IltAbstractDirectImageBaseRendererFactory implementation that provides an ilog.tgo.graphic.renderer.IltBaseRenderer implementation that is used to render the custom LED types. This implementation, renderer.LedBaseRendererFactory.BaseRenderer extends the ilog.tgo.graphic.renderer.IltLedBaseRenderer in that it draws the image retrieved from CSS

This sample is composed of one JSP file: index.jsp that is located in webpages directory. This JSP file defines all the JViews Framework and JViews TGO Faces components that compose and support the sample's user interface. For example, the Network and Equipment View Faces components are initialized in this file to use as their IlpContext and their associated component (IlpNetwork and IlpEquipment respectively), the IlpContext and component instances that are contained in the SampleContext. The standard JSF Expression Language syntax is used to specify these associations: <jvtf:networkView context="#{sampleContext.context}" network="#{sampleContext.network}" ... > or <jvtf:equipmentView context="#{sampleContext.context}" equipment="#{sampleContext.equipment}" ... >.

This sample has the following directory structure:

webpages/resources/configuration/deployment
Contains the JView TGO deploment settings (deploy.xml)
webpages/resources/data
Contains the network data file that is displayed in the both Network and Equipment views (network.xml)
webpages/resources/images/backgrounds
Contains the image that is used as the Network view background (us-map.jpg)
webpages/resources/images/cards
Contains the images that are used to represent the custom cards
webpages/resources/images/ports
Contains the images that are used to represent the custom ports
webpages/resources/images/leds
Contains the images that are used to represent the custom LEDs
webpages/resources/images/popup
Contains the images that are used by the contextual menu.
webpages/resources/images/toolbar
Contains the images that are used by the toolbar.
webpages/resources/styles/equipment
Contains the CSS files that define the Equipment view's:
- Configuration (equipment.css)
- Look-And-Feel (cards.css, leds.css, object.css and ports.css)
webpages/resources/styles/network
Contains the CSS files that define the Network view's:
- Configuration (network.css)
- Look-And-Feel (cards.css, leds.css, object.css and ports.css)
webpages/resources/styles
Contains the HTML CSS styles file that customize the Look-And-Feel of the HTML page itself (style.css)

For more details see the resource and source files themselves.

Installation Directory

The JSF Integration - Equipment Viewer sample is installed here.