Logistics Sample Application: Design

This section describes the design philosophy of the Logistics Sample Application to showcase the development, design, and deployment of a complete enterprise application using various Sun™ ONE products.

This section contains the following topics:

• Design Philosophy
• Architecture Overview
• Detailed Design of Logistics
• Packaging and Deployment
• Directory Structure
• User Profile and Access Control Management
• Internationalization
• Screen Flow Diagrams

Design Philosophy

---

The design of the Logistics Sample Application is based upon the patterns and best practices that are advocated by Sun's Blueprints (see http://java.sun.com/blueprints).

The intention of this application is to showcase development, design, and deployment of a complete enterprise application using various Sun ONE products. The Sun ONE Developer Studio is used as the primary development, packaging, debugging, and deployment platform. The diagram below showcases the various components of the Sun ONE Web Services Platform Developer Edition that are used in the application.

The architecture section addresses high-level design features, and subsequently navigates to implementation details of the Logistics Sample Application.

This document is provided as an online-only resource so that it may be continually extended and updated as both J2EE™ technologies and the sample application evolve. This document begins with a description of the separate applications that the sample application comprises, describes the modular structure of the Logistics Sample Application, and provides an in-depth description of several pieces of the modules.

The design is based upon abstracting the application into distinct tiers:

• The presentation layer.
• The Web layer.
• The service layer.

Presentation logic is separated from the business logic, Servlets are used for control and JSP pages for presentation, EJBs are used to manage business components.

Best practices and patterns are applied in each tier, making the application modular and distributable.

Architecture Overview

---

The Logistics Sample Application implements several patterns that are described in Blueprints. These choices impact the overall structure of the application, making it layered, modular, and distributable. Some of the salient features of the Logistics Sample Application design are listed below.

Sun ONE Application Framework

The Logistics Order Center uses the Sun ONE Application Framework (formerly JATO) to dispatch, control, and manage page flow. It is an MVC (Model-View-Controller) based framework. The consistent structure and MVC functional separation imposed by the framework makes applications more reliable and easier to maintain and extend. The Cargo Line Customer Order Center interface uses the Sun ONE Application Framework and showcases two ways of accessing data:

• Via the Query model.
• Accessing functionality via the Facade interfaces.

Enterprise Java Bean Components

Enterprise beans technology is used to provide scalability, reliability, a component-based development model, and common horizontal services such as persistence, asynchronous communication, and declarative transaction and security control. The Logistics Sample Application uses Enterprise Beans technology for both business logic and persistence.

• Remote Session Beans

The facades themselves are defined as Remote session beans (stateless), providing an entry point into the system. They are modeled as session facades, which are coarse grain interfaces into the Logistics Sample Application backend. Since they are remotable, they can be accessed across networks, making them distributable. Additionally, they hide the fine grained interfaces from the Web layer. All business logic is handled by this layer.

• Local Entity Beans

The Logistics Sample Application uses Local Entity beans which interact with the database layer. The facades interact with the Entity beans, accessing the fine-grained interfaces they would need. While Remote interfaces make the components distributable, they have an overhead cost of remote communication, serialization, and network latency.

Entity beans usually reside in the same JVM as the Remote session beans, and are made local in this application, thus avoiding costly remote procedure calls. Local enterprise beans provide high-performance access to fine-grained business logic, while maintaining the high-level services of an enterprise beans container.

Exposing Session Facade as Web Services

Since the Logistics Sample Application follows the Session Facade pattern to handle all business logic (Remote Session beans, as described above), these can be exposed as Web services. This adds another dimension of extending the architecture, so that different portions of the application can be accessed in multiple ways, with minimal coding. A well layered architecture ensures code reuse.

Container Managed Persistence and Container Managed Relationships

The Logistics Sample Application uses container managed persistence and Container managed relationships to insert, update, and query data. By using CMR, data consistency is also ensured without having to code for it. Since these are managed by EJB Container, application developers can focus more on developing application logic and integration points. All of these help in developing an application faster.

Declarative Transaction Control

J2EE transactions can be controlled programmatically in code or declaratively in deployment descriptors. Declarative transactions are easier to create and manage, while programmatic transactions offer a higher degree of control. The Logistics Sample Application uses declarative transaction control when updating data though the facades.

Declarative Security (Use of DSAME)

The Logistics Sample Application uses the Sun ONE Directory Server Access Management Edition (DSAME) along with the Sun ONE Policy Agent to ensure that the user is authenticated for each request.

The Agent Realm component of the Sun ONE Policy Agent for the Sun ONE Application Server 7.0 provides a runtime mapping of various principals in the Sun ONE Identity Server, with abstract security role names used by the hosted application, to determine whether the currently authenticated user is authorized to access the administration module, or is otherwise a member of a Customer role. Authorization is also performed programmatically within the administration module to refine the access control.

Synchronous and Asynchronous Communication

Synchronous communication is most useful when an operation can produce a result in a reasonable amount of time. Asynchronous communication is more complex to implement and manage, but is useful for integrating high-latency, unreliable, or parallel operations. The Logistics Sample Application uses Message Queue to transfer insurance requests to the Insurance Agency, whereas getting the details of a shipment by the insurance client is a synchronous communication.

Detailed Design of Logistics

---

This section describes in detail various modules of the Logistics Sample Application, which are:

• Cargo Line Administration Module.
• Cargo Line Order Center Module.
• Cargo Line Web Services Module.
• Insurance Agency.
• Database Schema.

Each module has code snippets to showcase the implementation and design philosophy.

Cargo Line Administration Module

Overview

The Cargo Line Administration Module Layers diagram below shows the different layers of the Cargo Line Administration module.

   Cargo Line Administration Module Layers

Architecture details of the Administration module are as follows:

Web Layer

The design of the Web layer of the Cargo Line Administration module is based upon the J2EE Blueprints pattern, FrontController, to centralize the processing of all incoming requests.

For more information regarding the FrontController pattern, refer to http://java.sun.com/blueprints/patterns/catalog.html

Front Controller

All HTTP Requests go to the CargolineFrontController servlet which acts as a Front Controller. Each HTTP Request passes two parameters:

• Event
• Action

Based on the Event, the Front Controller directs the request to an event handler. The mapping of an event to an event handler takes place in RequestProcessor. When getting the results back from the event handler, the FrontController directs the request to FlowManager to display the next page.

The Code in CargolineFrontController Servlet figure below shows a snippet of code that appears in the CargolineFrontController servlet.

   Code in CargolineFrontController Servlet

RequestProcessor

The FrontController directs the requests to a RequestProcessor. The RequestProcessor maps the event to an appropriate event handler, instantiates the handler, and passes the request to the handler. The handler then contacts the required Session Facade based on the parameter Action of the request. The results are obtained from the Facade as a Data Transfer Object, a serializable object. As the mapping of an event to the event handler is defined in a property file, this enables new functionality to be added without disturbing the existing code, making the application extensible.

The Code in RequestProcessor figure below shows a snippet of code that appears in the RequestProcessor.

   Code in RequestProcessor

The mapping of events to handlers is defined in a properties file, mappings.properties.

The Code in mappings.properties File figure below shows a snippet of code that appears in the mappings.properties file.

   Code in mappings.properties File

EventHandler

Each event is handled by an event handler. The handler in turn handles all of the actions associated with the event.

An example of an event is Shipment. The handler of the Shipment event is ShipmentHandler, which handles all of the actions associated with the shipment including adding, deleting, and searching for a shipment.

The Code in ShipmentHandler figure below shows a snippet of code that appears in ShipmentHandler, and how the handler manages each action associated with the Shipment event.

   Code in ShipmentHandler

FlowManager

The FlowManager, a Singleton, determines the next page that is displayed to the user. The FlowManager determines the next page based on the Event, Action, and the status of the request. The FlowManager also takes the locale into account when finding the next page.

The Code in ScreenFlowManager figure below shows a snippet of code that appears in ScreenFlowManager.

   Code in ScreenFlowManager

The next screen is chosen based on the screen mapping defined in the properties file, mappings.properties.

The Code in Screen Mapping Defined in mappings.properties File figure below shows a snippet of code that appears in RequestProcessor.

   Code in Screen Mapping Defined in mappings.properties File

Service Layer

Facades

Facades are the entry point into the services layer. Various clients access the business functionality and data through the Facades.

Facades are coarse grain interfaces that centralize interactions from the client or Web tier to the fine grained business entities. They are remote objects, and can therefore be accessed in a variety of ways.

For more information, refer to Session Facade pattern at http://java.sun.com/blueprints/patterns/catalog.html.

Entity Beans

Entity Beans are used to access the database and provide fine grained interfaces that the facades need to perform the task. These interfaces are not exposed directly to the Web tier. Moreover, these Entity beans are defined as Local, as the facades and the beans exist within the same JVM. Making these local improves performance.

Data Transfer Object

Data Transfer Object, or Value Object, is a serializable class that groups related attributes forming a composite value. This class is used as the return type of remote business methods or facades. Clients receive instances of this class by calling coarse-grained business methods, and locally accessing the fine-grained values within the transfer object. Fetching multiple values in one server round-trip decreases network traffic and minimizes latency and server resource usage.

For more information, refer to Data Transfer pattern at http://java.sun.com/blueprints/patterns/catalog.html.

Service Locator

The Service Locator pattern centralizes distributed service object lookups, provides a centralized point of control, and may act as a cache that eliminates redundant lookups. It also encapsulates any vendor-specific features of the lookup process. In the Logistics Sample Application, the Service Locator is used to look up any Entity Beans, datasources, and JMS Resources.

For details on this pattern, refer to Service Locator at http://java.sun.com/blueprints/patterns/catalog.html.

Cargo Line Order Center Module

Overview

The Cargo Line Order Center Module figure below shows the different layers of the Cargo Line Order Center module.

   Cargo Line Order Center Module

The Customer Order Center is the module of the Logistics Sample Application that provides the external interface for the Cargo Line customers. Through a Web browser, customers can create new shipments and manage their profiles. This document presents a look at the Customer Order Center from a design and development point of view.

Design

Sun ONE Application Framework

The Customer Order Center was implemented using the Sun ONE Application Framework. The Sun ONE Application Framework is based upon state-of-the-art design patterns and techniques, such as MVC, Service-to-Workers, Hierarchical View, Command, Business Delegate, and others.

Additionally, the Sun ONE Application Framework is based on an N-tier JSP/Servlet architecture. The Sun ONE Application Framework has been designed entirely around interfaces and object contracts that reflect these patterns. It is an integrated set of cooperating design patterns first, and an implementation of those patterns second.

For more information about the Sun ONE Application Framework, see http://wwws.sun.com/software/products/application_framework

Customer Order Center

The Customer Order Center illustrates powerful and proven design concepts and paradigms that are imposed by the Sun ONE Application Framework. Primary among these concepts is the MVC pattern. The customer order center takes advantage of the various Sun ONE Application Framework components with an emphasis on the SQL Model, which provides application data resource transparency to a RDBMS.

The flexibility provided by the Sun ONE Application Framework allows the developer the discretion of using as much or as little of that software as desired. The customer order center takes advantage of this flexibility when creating or deleting customer shipments. Creating and deleting a shipment required a more complex processing of the Logistics Sample Application involving the backend datasource schema. Therefore, the use of a session bean facade was chosen to implement these two operations. The Customer Order Center shows the integration of the Sun ONE Application Framework components with direct J2EE coding to illustrate this flexibility.

Packaged with the Customer Order Center is the jato-2_0_0.jar archive file. This jar file contains the Sun ONE Application Framework compilation and runtime libraries. This file is provided by the Sun ONE Application Framework plugin when a new Sun ONE Application Framework project is created. This file is located in the WEB-INF/lib directory of the order center module. The Running Logistics section of this guide specifies the creation of the common.jar and CargoLineJARClient.jar files that are also needed in the WEB-INF/lib directory of the Order Center modules.

Development

Development is done with the Sun ONE Studio, with the Sun ONE Application Framework installed. The Sun ONE Application Framework provides rapid visual development of Web applications based on its time-tested framework runtime, and the industry standard J2EE platform. The Sun ONE Application Framework project presented in its own tab on the Explorer window is called Sun ONE Web Apps. This tab provides a more Sun ONE Application Framework-centric view of your project, in addition to those provided by the Sun ONE Studio. Examples include setup wizards to create ViewBeans, Models, and Command classes, automatic generation of common Sun ONE Application Framework code and markup in files, ease of setup for WebActions, auto model execution, and so on.

The Sun ONE Studio Explorer figure below shows the Sun ONE Web Apps tab.

   Sun ONE Studio Explorer

The SQL Model provided by the Sun ONE Application Framework is the main data value source used by the Customer Order Center. It is responsible not only for the execution of a given SQL statement, but for the general management of where clauses and query results. The Customer Order Center uses various SQL models that map to the customer, shipment, or port tables in the database schema. These models in turn can be used interchangeably by the various Customer Order Center viewbeans.

The Code in SQL Model figure below shows a snippet of code that appears in a SQL Model mapped to a customer table, and how to retrieve data from the model.

   Code in SQL Model

Most of the tasks are performed by the Sun ONE Application Framework classes through interactions with the SQL Model. However a session bean was chosen to perform the task of creating and deleting shipments, given that these tasks had more complex processing of the Logistics Sample Application involved with the backend datasource schema.

The Code in Shipment Deletion Action figure below shows a snippet of code that appears in the shipment deletion action. This action is handled in the SearchShipmentTiledView.java class.

   Code in Shipment Deletion Action

The Code of the Create Shipment Action figure below shows a snippet of code that appears in the create shipment action. View the ShipmentRequestViewBean.java source file for the full code.

   Code of the Create Shipment Action

Because the value returned from createShipment() is a custom data transfer object (java bean), you need to manually extract its data into the resulting confirmation display.

The first action of this class is to set its primary model to the default model associated with all view beans. In beginComponentDisplay(), the tiled views display fields are set with data retrieved from the custom data transfer object, at which point the data is rendered in the JSP file after this method executes.

The Code in TiledView Class figure below shows a snippet of code that appears in the TiledView class in which you are trying to populate a TiledView class with data from the custom data transfer object (Java Bean).

For the full code, see the ShipmentConfirmationTildedView.java source file.

   Code in TiledView Class

Cargo Line Web Services Module

Cargo Line exposes the methods to edit/get UserProfiles, get Port, Routes, and Shipment Details, and to create/update the Shipments as Web services. The consumer of the Web Services is the Insurance Agency. These Web services are based on the JAXRPC servlet endpoint model. This module is deployed as an independent Web archive by Cargo Line.

The CargolineWebServicesImpl class implements the methods exposed as the Web services. The CargolineWebServicesImpl class communicates with the Session Facades in the Service layer, and these facades in turn communicate with the relevant Entity Beans. For example, the getShipmentDetails(int shipment_id) method invokes the getShipmentData(int id) on the remote instance of the ShipmentFacade Session Bean. The getShipmentData(int) method return ShipmentData Object, and the wscompile tool generates the required (de/) serializers for this type of custom objects.

For more information on creating Java Web services, refer to http://java.sun.com/webservices/docs/1.0/tutorial/doc/JAXRPC.html.

The Code in CargolineWebServicesImpl figure below shows a snippet of code describing how CargolineWebServicesImpl invokes the getShipmentData(int shipment_id) method on the ShipmentFacade.

   Code in CargolineWebServicesImpl

Insurance Agency

Insurance Agency Client

The Insurance Agency Client is a standalone rich client that was developed using Java Swing, and is used by the Insurance Agency Employees. The Insurance Agency Client communicates with its local database and displays the list of customer shipments pending/approved/denied in the data base. Employees can select a shipment to view the details.

To view the details of the shipments, the Insurance Agency client internally uses JAX-RPC to communicate with the JAX-RPC based Cargo Line Web services. This client uses the stub-based model of the JAX-RPC API. The client makes calls to the methods on the CargoLineWebServiceIF stubs generated by the wscompile tool.

Client Side

The Insurance Agency client gets the selected shipment ID and invokes the getShipmentDetails(int id) on the CargoLineWebServicesIF stub objects. To call a remote procedure, the Insurance Agency program invokes the getShipmentDetails(int id) method on the stub, which is a local object that represents the remote service. The stub invokes routines in the JAX-RPC runtime system. JAX-RPC serializes all of the required objects into XML, converts the remote method call into a SOAP XML message, and transmits the message as an HTTP request to the CargoLineWebServicesIF port. When a response is received, the JAX-RPC runtime system extracts the SOAP message from the HTTP response and translates it into a method response.

Server Side

When the server receives the HTTP request, the JAX-RPC runtime system extracts the SOAP message from the request and translates it into a method call. JAX-RPC invokes the method on the tie object. The tie object invokes the method on the implementation of the CargoLineWebServicesIF service. The JAX-RPC runtime system on the server serializes any objects, converts the methods response into a SOAP message, and then transmits the message back to the client as an HTTP response.

The client then builds the ShipmentData object from the received XML response and displays the details in a message dialog window.

The Insurance Agency Client: Client/Server/Soap Message figure below shows the Client, Server, and Soap Message relationships to one another.

   Insurance Agency Client: Client/Server/Soap Message

Message Queue

The Sun ONE Cargo Line works with the Insurance Agency whenever a customer wants to insure the shipment. The Insurance Agency has its own database, with a table called Shipment, where the table definition is the same as the Shipment table in Cargo Line.

The Insurance Agency is notified whenever an insured shipment is created in Cargo Line. It is assumed that the Insurance Agency may not always be running.

Therefore, this notification utilizes the message queue that is included with the Sun ONE Application Server. Messages of insured shipments are saved in the message queue until they are sent to the Insurance Agency.

The point-to-point approach to messaging is used here.

The Message Queue: Point-to-Point Approach figure below shows the messaging process between the Sun ONE Cargo Line and the Insurance Agency database.

   Message Queue: Point-to-Point Approach

A point-to-point (PTP) application is built around the concept of message queues, senders, and receivers. Cargo Line sends the insured shipment message to the Logistics Sample Application queue.The Insurance Agency consumes the messages from the queue. Queues retain all messages sent to them until the messages are consumed.

Database Schema

Cargo Line Database Schema

The Cargo Line Database Design figure below shows the ER diagram for the Cargo Line database.

   Cargo Line Database Design

Packaging and Deployment

---

The Java™ 2 Platform, Enterprise Edition, enables developers to assemble applications from components. A J2EE component (such as a servlet or an enterprise bean) is an independent functional software unit that conforms to interfaces defined by a component specification, and has only explicit dependencies on its environment. A component may be a single class, but more often is a collection of classes, interfaces, and resources. The Logistics Sample Application is comprised of the following components:

• Session and entity enterprise beans.
• Servlets, JSP pages, and supporting classes for Cargo Line admin.
• Servlets, JSP pages, and supporting classes for the Customer Order Center.
• Cargo Line Web services.

The above components are grouped into four modules:

• Cargo Line EJB module.
• Admin Web module.
• Order-Center Web module.
• Cargo Line Web services Web module.

All J2EE modules are independently deployable units.

EJB Module

In general, there are three options to package components into EJB module:

• Package each enterprise bean for an application in its own EJB module.
• Package all enterprise beans for an application in one EJB module.
• Package all related (closely-coupled) enterprise beans for an application in one EJB module.

The third option is more modular and is recommended for most J2EE applications. It strikes the right balance between maximum reusability (option 1) and maximum simplicity (option 2). In the Logistics Sample Application, there are no third-party components. All entity EJBs are CMR entity beans, session facade EJBs are closely related to CMR entity beans. Enterprise beans that depend on one another should be grouped together in the same JAR file for both organizational and performance reasons. The CargolineJAR EJB module was used to hold all enterprise beans in this application.

Web Modules

A Web module that has a clearly defined purpose is easier to reuse in different scenarios than one with less well-defined overall behavior. In the Logistics Sample Application, Web components are packaged into three Web modules along their functionality line:

• Cargoline-admin war.
• Order-Center war.
• Cargo Line Web service war.

Utility classes are grouped into library (common.jar) and are put under the Web module's WEB-INF/lib.

When a Web component uses enterprise beans, package the EJB component's client EJB jar (CargoLineJARClient.jar) in the Web archive WEB-INF/lib directory. Putting the client EJB jar in this directory places the files in that JAR in the Web container's classpath.

Deploy Application

After creating the modules for the Cargo Line application, you can deploy those modules independently (as described in the logistics user guide) or you can create and configure a J2EE application that includes all of those modules.

The Deploy Modules Independently figure is shown below.

   Deploy Modules Independently

The Group Modules Into J2EE Application figure is shown below.

   Group Modules Into J2EE Application

To assemble different modules into a J2EE application and deploy it as a single unit you can:

• Create a J2EE application node from the Sun ONE Studio filesystem.
• Add modules to this J2EE application.
• Set Web context for the Web modules.
• Link EJB references.
• Resolve security role mapping.

The Sun ONE Studio greatly simplifies the process of packaging and deployment. It allows you to control the contents of a deployment descriptor by working with module and application property sheets. The IDE also allows you to view the actual XML deployment descriptors and edit them.

Directory Structure

---

The following section details the directory structure of the Logistics Sample Application. The directory structure is arranged keeping the following points in mind:

• Functionally separate

The source is organized so that it is functionally separate.

The Cargo Line Co.'s src is kept under logistics/cargoline/src, and the Insurance Co src is under logistics/insurance/src.

• Studio centric

Each of the directories are mounted from the Sun ONE Studio Filesystem.

The Java packaging structure itself provides a directory structure, and all of the sources could be bundled under one src/com/logistics directory. For Logistics, the functional breakdown was also done on top of Java packaging structure so that there was clear demarcation in sources, and secondly, packaging exercise became easier.

Cargo Line Co.

Following is the directory structure under logistics/cargoline/src. All source for Cargo Line is kept under <install_root>/samples/logistics/cargoline.

apps

All of the Web applications are organized under apps dir. These are the various Web interfaces that access the common backend or business layer of Cargo Line. Each of the directories are packaged as a Web module. Each of the directories have a WEB-INF/classes dir, where all the Java src is kept.

Refer to packaging for more details on the packaging of Cargo Line.

admin

This contains the sources for the Cargo Line Administration module.

ordercenter

This contains the sources for the Cargo Line Customer order interface.

webservice

This contains the sources of the Cargo Line Web service module.

components

All business logic, persistence, and common classes are kept under this directory.

business

Contains all Data Transfer Objects. As the name suggests, these classes transport data from the service layer to the Web layer. Refer to the architecture diagram for more details.

common

All common classes, Exceptions, Localization classes, Resource bundles are kept under this directory.

controller

Here are all the facades, which are stateless session beans. This has the Home and Remote Interfaces, the bean and all Sun ONE Studio generated files.

entity

Here are all the Entity beans, which are Local. The facades interact with these Entity beans.

jms

Contains all of the classes related to messaging.

routing

This directory contains classes for the Routing Algorithm. This determines the path a shipment is going to take from the source port to the destination port. This is a stateless session bean.

Insurance Co

Following is the directory structure under logistics/insurance/src. All source for Cargo Line is kept under <install_root>/samples/logistics/insurance.

client

Contains all the sources for the rich client for Insurance agents.

common

Contains common components and utilities, such as Message Consumer.

User Profile and Access Control Management

---

The Cargo Line application uses the Sun ONE Directory Server Access Management Edition (DSAME 5.1) along with the Sun ONE Policy Agent to manage the user profile and secure access to protected Web-based resources.

Authentication and Authorization

A user must first be authenticated when requesting access to the Cargo Line application via a Web browser. The request is redirected to the DSAME authentication service.

This module determines the type of authentication to initiate based on the method chosen by the user's organization. For the Cargo Line, user name and password based LDAP authentication is pre-defined. The authentication module sends an HTML form to the Web browser. Having obtained the user's credentials, the Authentication module calls the respective provider to perform the authentication. Once verified, the module generates a Single Sign-On (SSO) token (using the SSO API) which holds the user's identity. The SSO API then generates a SSO token ID, a random string associated with the SSO token. This ID is then sent back to the browser in the form of a cookie.

Once authenticated, the authentication component re-directs the user back to the requested page.

Cargo Line defines four roles:

• RAG

Routing agents are responsible for managing ships, ports, routes, and voyage information. They can add/update/delete ships, ports, routes, and voyages.

• CAG

Customer agents are responsible for managing customer information and shipment information. They can add/update/delete customer details, create/update/cancel shipment requests for customers.

• MGR

Managers are the super users of the Cargo Line system. In addition to doing the tasks of Routing agents and Customer agents, they can create new administrators, and update/delete membership information for other administrators (Routing and Customer agents).

• CST

Customers can only access Cargo Line Order Center to edit their customer profile and request shipments.

The Agent Realm component of the Agent for Application Server 7.0 provides runtime mapping of various principals in the Sun ONE Identity Server, with abstract security role names used by the hosted application to determine if the currently authenticated user is authorized to access a particular resource, or is otherwise a member of a given role.

This runtime evaluation can occur only if the user is authenticated as a Sun ONE Identity Server principal by means of the Sun ONE Identity Server's authentication service. Without the user being authenticated appropriately, the results of such evaluations by the Agent Realm is always negative, resulting in access being denied to the user for the requested resource.

It is the Agent Filter component that enforces authentication for users who try to access particular application resources, thereby enabling the Agent Realm component to correctly evaluate the principal mappings as desired.

In the Cargo Line Administration module, role to principal mapping is defined in its sun-web.xml.

<sun-web-app>
  <security-role-mapping>
    <role-name>CAG</role-name>
    <group-name>cn=CAG,o=Cargoline,o=isp</group-name>
  </security-role-mapping>
  <security-role-mapping>
    <role-name>MGR</role-name>
    <group-name>cn=MGR,o=Cargoline,o=isp</group-name>
  </security-role-mapping>
  <security-role-mapping>
    <role-name>RAG</role-name>
    <group-name>cn=RAG,o=Cargoline,o=isp</group-name>
  </security-role-mapping>

....
....
  </sun-web-app>

The agent filter is defined in web.xml.

<web-app>
  <display-name>CargoLineAdminWAR</display-name>
  <filter>
    <filter-name>Agent</filter-name>
    <display-name>Agent</display-name>
    <description>SunONE policy agent</description>
    <filter-class>com.sun.amagent.as.filter.AgentFilter</filter-class>
  </filter>
  <filter-mapping>
    <filter-name>Agent</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

...
...
</web-app>

User Profile Management

The Cargo Line application uses interfaces (SDK) provided by the Identity Management module of DSAME to create, modify, and delete Cargo Line user profiles. These identity related data are stored in LDAP based Directory Server.

Following is the code example of how to get all Cargo Line users in UserBean.java:

public java.util.Collection ejbFindAll() throws javax.ejb.FinderException {
     Collection userIds = new HashSet();
     AMPeopleContainer amPC = null;
     try {
        getConnection();
        amPC = amsConn.getPeopleContainer(peopleDN);
        if ( !amPC.isExists() )
             throw new javax.ejb.ObjectNotFoundException("DN " + peopleDN + " does not exist");

        Set resultSet = amPC.searchUsers("*", AMConstants.SCOPE_SUB);

       if (resultSet != null && resultSet.size() > 0) {
           Iterator iter = resultSet.iterator();
           while (iter.hasNext()) {
                String uDN = (String) iter.next();
                   userIds.add(getCN(uDN));
           }
        } else
           throw new javax.ejb.ObjectNotFoundException();
     } catch (SSOException ex1) {
        throw new javax.ejb.FinderException("Invalid SSO Token.");
     } catch (AMException ex) {
         throw new javax.ejb.FinderException("an error is encountered when trying to access/retrieve data         from the data store");
     }
     return userIds;
 }

Internationalization

---

The Logistics Sample Application was designed to accommodate issues related to internationalization (i18n) and localization (l10n).

The Logistics Sample Application addresses i18n by providing a convenience class called Localiser.java. This class is used throughout the Logistics Sample Application to retrieve locale specific content. It internally stores the current locale, a resource bundle, and several utility methods to that address date, string, number and currency display and formats among different locales. The Localiser.java class can be viewed under <install_root>/samples/logistics/cargoline/src/components/common/com/sun/developerplatform/logistics/cargoline/common.

l10n is supported using a parallel content approach, which is the use of parallel sets of JSPs, with each JSP in the set customized to a particular language.

For example, the administration modules supports this by programmatically specifying a different directory containing locale specific JSP files based on the current locale of the application. The default directory is /jsp/default under the admin SRC tree which contains JSP files for the english locale. If the current locale is French, the Logistics Sample Application would direct to and display JSP files located in the /jsp/fr directory.

Screen Flow Diagrams

---

The following screen flow diagrams are shown in this section:

• Cargo Line Administration console.

• Flow for Agents, ships, ports, routes and customers.
• Flow for Voyages.
• Flow for Shipments.
• Cargo Line Order center flow.
• Cargo Line Administration Module.

Flow for Agents, ships, ports, routes and customers.

The Screen Flow diagram below describes the screen flow for the screens mentioned.

   Screen Flow

Flow for Voyages

The Flow for Voyages diagram below describes the screen flow for the Voyages screen in the Cargo Line Administration console.

   Flow for Voyages

Flow for Shipments

The Flow for Shipments diagram below describes the screen flow for the Shipment screen in the Cargo Line Administration console.

   Flow for Shipments

Cargo Line Order Center Module

The Cargo Line Order Center Module Screen Flow diagram is shown below.

   Cargo Line Order Center Module Screen Flow