EDN: ESRI Developer Network
Now that you understand more about the JSF framework, you will build a simple Web application that allows the user to zoom in, zoom out, and return to full extent for a map. The foundation of working with the ESRI Web ADF will be covered by this example. The discussion in the rest of this document assumes you are familiar with the JSF framework and Java Web applications. If not, please see the list of resource listed at the end of the introductory article. This example application is titled "ags_simple" and is included with ArcGIS Server for the Java Platform. This article assumes there is a server object as service being hosted with the name usa, which uses the map document found in the /samples/data/mxds directory. Run arcgisant in the sample directory; either import the source folder or the WAR file into your 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 from the article. Running this sample produces a Web application that looks like this:
For this example there are only two files to examine, faces-config.xml, found in the WEB-INF folder, and map.jsp, found 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 framework, expose those objects to the view/Web tier, identify the appropriate GIS servers for the application, and provide authentication information where appropriate. Map.jsp contains the JSP tags to provide the rendering of the map application, such as a map, a table of contents, and tools for working with the map. The data, which will be used to create this visual view, is once again tied back into the data sources identified in the faces-config.xml file.
When you open the faces-config.xml file, the first managed Bean you will see is for the WebContext (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 attribute HashMap. The attribute HashMap 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 to have associated with the life span of the context.
Inside the 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, this snippet
<managed-property> <property-name>attributes</property-name>
<map-entries>
<map-entry>
<key>map</key>
<value>#{map}</value>
</map-entry> </map-entries> </managed-property>
stores under the key, map, a managed Bean with the name 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.
These tier 1 objects are loaded into memory upon their first use 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 will never 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.
This snippet indicates there will be a managed Bean, ags, which in this case, is an ArcGIS Server connection:
<managed-property> <property-name>resources</property-name>
<list-entries>
<value>#{ags1}</value>
</list-entries> </managed-property>
Each resource associated with the context needs a managed Bean to handle the communication with that particular data source. For this example, you will only have one resource, which uses an ArcGIS Server. Following is an example for ArcGIS Server:
<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 Server. After these elements, you declare the ArcGIS Server machine you want to connect to 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 which registers all the functionalities you want to expose on that specific resource. To make your application to communicate with more than one resource, list the other resources in the context declaration, then you will need managed Beans, one for each data source. Making an application that consumes multiple data sources will be covered in a later article.
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 TOC functionality. If you want to use other functionality, you would have to add a listing here and, where appropriate, a control and JSP tag to expose the functionality at the Web tier. You should notice that 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 into separate data source-specific files. You can find these files in the WEB-INF/functionalities folder.
The Web ADF uses a consistent naming convention for the managed Beans that expose functionalities. The ArcGIS Server functionalities are found 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 Server map functionality class is named AGSMapFunctionality, while the managed Bean is named 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 you want to connect to. This Bean should hold 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 is the same between two ArcGIS server installations then you can reuse the user Bean for both resources.
Other components of the faces-config file
Finally, the last two Beans in the file are used to manage the Web ADF framework. The referenced Bean is created internally to the application and is managed by the managed Bean, which is named esriWebSession.
The managed Bean declarations for all the tier 1 objects used in the application is in a separate configuration file, 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 into a separate file because you will rarely make edits to this file, and if you make the changes to the file in the blank template, all your applications will have those attributes. In this file, you can set the server-side properties for each control. An example would be the image format for the map, either PNG or JPG or the number of expanded levels for the TOC control. Here is an example of the declaration for the WebMap tier 1 object:
<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>
You are declaring a managed Bean named map to be of class WebMap. 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 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, which 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, please consult 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 instantiated.
Summary
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 it would work with, and establish which concrete data resources it would communicate with in model tier 2. You then add the rest of the 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 think of the entire stack from the diagram in the previous article. This time you can start from the bottom. If you have an ArcGIS Server and you want to show its map in your Web application, you need to
This provides the perfect transition to the next article. Now that you have wired the model tier 1 and model tier 2 together, it is time for you to build the view tier and connect it to the model tier.