In this topic
- Application requirements
- Context control
- Declaring resources and functionalities
- User beans
- Other components of the faces-config file
- Declaring other controls
- Wrap up
Application requirements
This topic assumes you are familiar with the JavaServer Faces (JSF) framework and Java Web applications. This application is titled ags_simple and is included with ArcGIS for Server for the Java platform. This topic also assumes there is a server object service being hosted with the name usa that uses the map document in the /samples/data/mxds directory.
To start, run arcgisant in the sample directory; either import the source folder or the Web Archive (WAR) file into your integrated development environment (IDE) so you can follow along. The actual sample can use a different server object and will have a different user name, password, domain, and host than those here. Running this sample produces a Web application as shown in the following screen shot:
For this application, the following two file are used:
- faces-config.xml in the WEB-INF folder
- map.jsp in the root of the Web application
The faces-config.xml file is used to connect the business objects that are part of the Web ADF, expose those objects to the view/Web tier, identify the appropriate geographic information system (GIS) servers for the application, and provide authentication information where appropriate. Map.jsp contains the JavaServer Pages (JSP) tags that provide the rendering of the map application, such as a map, a table of contents, and tools for working with the map. The data used to create this view is tied back into the data sources identified in the faces-config.xml file.
Context control
When you open the faces-config.xml file, the first managed bean you see is for WebContext (the context). While the context is a model tier 1 component, the context also acts as the manager for the other model tier 1 components. It connects the data sources to the controls and coordinates the control when there is an action that requires a refresh. To enable this coordination, all the other model tier 1 components are registered with the context as managed attributes. These attributes (such as WebQuery) are stored in the HashMap attribute. The HashMap attribute can also be used to add your own classes that you want managed by the context or other arbitrary information, such as user name, that you want associated with the life span of the context.
In the Extensible Markup Language (XML) file, each model tier 1 component is given a name to be used in the JSF framework, and JSF expression language (EL) is used to refer to a managed bean listed later in the file. For example, the following code example shows a managed bean called map stored under <key>map. Since the controls use the model tier 1 objects to access and manage their data, for each control on the JSP page, there must be an appropriate model tier 1 object registered with the context.
[XML]
<managed-property>
<property-name>attributes</property-name>
<map-entries>
<map-entry>
<key>map</key>
<value>#{map}</value>
</map-entry>
</map-entries>
</managed-property>
The tier 1 objects are loaded into memory when they're first used in the application. Therefore, if you leave an entry for a tier 1 object in the attributes list but never add the tag to the page for the control, then it won't be instantiated. For example, if you write a pure mapping application but have an entry for a geocode tier 1 object, the geocode object will never be instantiated.
The only other information in the context control is a list of the resources used in the application. There should be an entry for each data source the application will use for data. Again, the syntax for each resource uses JSF EL to reference a managed bean containing the appropriate connection information.
The following code example indicates there will be a managed bean called ags, which in this case, is an ArcGIS for Server connection:
[XML]
<managed-property>
<property-name>resources</property-name>
<list-entries>
<value>#{ags1}</value>
</list-entries>
</managed-property>
Declaring resources and functionalities
Each resource associated with the context needs a managed bean to handle the communication with that particular data source. For this example, you have one resource that uses an ArcGIS server. The following code example is for ArcGIS for Server:
[XML]
<managed-bean>
<managed-bean-name>ags1</managed-bean-name>
<managed-bean-class>com.esri.adf.web.ags.data.AGSMapResource</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
<managed-property>
<property-name>user</property-name>
<value>#{agsUser1}</value>
</managed-property>
<managed-property>
<property-name>serverObjectName</property-name>
<value>usa</value>
</managed-property>
<managed-property>
<property-name>hosts</property-name>
<list-entries>
<value>YourServer</value>
</list-entries>
</managed-property>
<managed-property>
<property-name>functionalities</property-name>
<map-entries>
<map-entry>
<key>map</key>
<value>#{agsMap}</value>
</map-entry>
<map-entry>
<key>overview</key>
<value>#{agsOverview}</value>
</map-entry>
</map-entries>
</managed-property>
</managed-bean>
As with all other managed beans, the first three elements are the required elements for a bean: name, class, and scope. The AGSMapResource class is the concrete implementation of GISResource for communicating with ArcGIS for Server. After these elements have been established, declare the ArcGIS for Server machine to which you want to connect and the appropriate ArcGIS Server object; in this case, the Server is YourServer and the MapServer object is usa. Next is a reference to a managed bean that stores all the user authentication information. Finally, a resource managed bean contains a HashMap that registers all the functionalities you want to expose on that specific resource. For your application to communicate with more than one resource, list the other resources in the context declaration, and obtain a managed bean for each data source.
The Web ADF provides functionalities for all five of its data sources, each one with only the appropriate functionalities. In this example, you are using Map and table of contents (TOC) functionality. If you want to use other functionality, you must add a listing here and, where appropriate, a control and JSP tag to expose the functionality at the Web tier. The functionalities are declared using managed beans. Since adding new functionalities to a resource is an advanced tag, and to simplify the faces-config.xml, the declaration of the functionalities has been moved to separate data source-specific files. These files are located in the WEB-INF/functionalities folder.
The Web ADF uses a consistent naming convention for the managed beans that expose functionalities. The ArcGIS for Server functionalities are located in the Javadoc, and the managed bean name for each functionality is the source name, in all lowercase, with the functionality name using camel case. For example, the ArcGIS for Server map functionality class is AGSMapFunctionality, while the managed bean is agsMap. If you want a resource to appear in your map, you must declare the functionality with that resource. The inverse is also true; if you want to use a resource, but not all its functionality, the only step required is to omit unwanted functionalities from your faces-config.xml file with that resource.
User beans
You can write a user bean for each resource to which you want to connect. This bean holds the authenticating information appropriate to the resource. You can also reuse the same bean in several resources. For example, if the user name, password, and authenticating domain are the same in two ArcGIS for Server installations, you can reuse the user bean for both resources.
Other components of the faces-config file
The last two beans in the file are used to manage the Web ADF. The referenced bean is created internally to the application and is managed by the managed bean named esriWebSession.
Declaring other controls
The managed bean declarations for all the tier 1 objects used in the application are in a separate configuration file called context-attributes.xml. It has the same syntax as a faces-config.xml file, and your web.xml file associates this file with the Faces servlet. The configuration for these objects has been moved to a separate file because you will rarely make edits to this file; if you do make changes to the file in the blank template, all your applications will have those attributes. You can set the server-side properties for each control in this file. An example is the image format for a map, either Portable Network Graphics (PNG) or Joint Photographic Experts Group (JPG), or the number of expanded levels for the TOC control. The following code is an example of the declaration for the WebMap tier 1 object:
[XML]
<managed-bean>
<managed-bean-name>map</managed-bean-name>
<managed-bean-class>com.esri.adf.web.data.WebMap</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
<managed-property>
<property-name>imageFormat</property-name>
<value>PNG</value>
</managed-property>
</managed-bean>
In this application, you are declaring a managed bean named map to be of the WebMap class. Since its scope is set to none, the scope will be managed by its calling object; in this case, the context managed bean. After these required elements are set, the rest of the elements are properties that can be set for the WebMap class. These properties are considered server-side because they control the server processing of the map data. For example, whether or not to stream Multipurpose Internet Mail Extensions (MIME) data to the client is a server-side property, while border color of the image is a client-side property. For the map, there are a few properties, such as height and width, that can be set both at the server and at the client. For a complete list of server-side attributes for each of the tier 1 objects, see the reference documentation for the controls.
You only need to declare managed beans for the actual tier 1 objects used in your application. Because the scope is set to none, declared but unused managed beans will not be instantiated.
Wrap up
The pattern followed in the faces-config.xml file is to wire together the pieces in model tier 1, declare the context and the other tier 1 pieces with which it will work, and establish the concrete data resources with which it will communicate in model tier 2. Add the remaining pieces in tier 1 that are needed to work with the context and their properties. After finishing with tier 1, the file moves to tier 2 where it creates a managed bean for each concrete resource used in the application and the functionalities exposed on each resource. Finally, there is the credential information for resources, which require authentication.
To expose a data source at the Web tier, you need to consider the entire stack. Start from the bottom. If you have an ArcGIS server and you want to show its map in your Web application, you need to complete the following steps:
- Declare your ArcGIS server with its MapServer object as a GISResource.
- Associate AGSMapFunctionality with that resource.
- Declare a WebMap in your application to use the functionality.
- Associate the WebMap with the context, insuring it participates in the Web ADF framework.
- Place the appropriate tags on the JSP page.