Core Development Guide

Chapter 2 About the SilverStream eXtend Director Application Architecture

This chapter describes the kinds of applications you can build with Director and gives an overview of the architecture of a Director application. It contains the following sections:

Director EAR and the application server

A Director application is packaged in a single Director EAR file that contains several WAR files and JAR files. You can create the EAR by running the Director EAR Wizard in SilverStream eXtend Workbench. The wizard lets you select the subsystems you want to use and specify configuration properties for these subsystems. After you've finished making your selections, the wizard creates an EAR project that includes the J2EE modules you need for your application.

At the top level of the EAR, you will see several WAR files. Some of these (such as PAC.war, PMC.war, and the WAR for your custom Web application with portal functionality) are prepackaged Web applications that can be modified or deployed as is. These can be thought of as Web tiers. Others (such as Boot.war and ResourceSet.war) are supporting WARs required for the Director application architecture. In addition to the Web tiers and supporting WARs, you will also see one or more service WARs, which are WARs that provide subsystem services. ContentMgmtService.war and WebDAVService.war are examples of service WARs.

cdAppArch1

Under the library folder, you will see several service JAR files. These JARs contain classes that provide core services for a Director application.

cdAppArch2

Once you've run the Director EAR Wizard, you can add additional custom Web applications or other application-specific J2EE modules to the EAR. You can also add or remove subsystems, or make any other necessary changes to the structure and content of the EAR, just as you would with any J2EE application.

When you're ready to deploy the application, you can use the facilities provided with Workbench to upload the EAR to one or more servers.

For more information For details on using the Director EAR wizard, see Configuring a Director Application.

EAR namespacing

The J2EE specification does not require the EAR name to be part of the context for a WAR file. This can be problematic when multiple EAR files with similar content are deployed to the same server. For example, if you deploy the PAC in several different EAR files to the same server, the application server will not be able to distinguish the different versions of the PAC. Director introduces the notion of EAR namespacing to solve this problem. The namespace is part of the URL for accessing the Director Web tiers and custom Web applications.

When you run the Director EAR Wizard in Workbench, you can specify that EAR namespacing be enabled in the project. To implement namespacing, Director prefaces the context for each WAR with the namespace you specify. The context for each WAR is specified in the application.xml file for the EAR. The Director EAR Wizard uses the name assigned to the EAR as the default namespace.

For example, suppose you enable namespacing for an EAR and specify a namespace of MyEAR. Each module section in application.xml has a context-root element that prepends the namespace to the WAR name. The module section for the Content Management subsystem would look like this:

  <module>
    <web>
      <web-uri>ContentMgmtService.war</web-uri>
      <context-root>/MyEAR/ContentMgmtService</context-root>
    </web>
  </module>

Other subsystems would have similar context-root entries.

When you deploy this EAR, you can use URLs like these to access the Director Web tiers (PAC and PMC):

  http://localhost/MyEAR/PAC/main
  http://localhost/MyEAR/PMC/main

NOTE On a SilverStream server, if you deploy to a database other than SilverMaster, the URL would also include the database name.

Classloading within a Director application

A WAR file can access classes in a JAR file that is contained within that WAR, as well as classes in a JAR file that is placed outside the WAR in some other location within the EAR. Director applications take advantage of both of these configurations.

Classpath for WAR When a WAR file uses the services of a JAR file within the WAR, the classes in the WAR have no difficulty locating the classes in the JAR, since these classes are automatically included in the WAR's classloading environment. However, when a WAR file uses the services of a JAR file that is located outside the WAR, the JAR must be added to the classpath for the WAR. J2EE applications do this by setting the classpath in the MANIFEST.MF file in the META-INF directory within the WAR. For example, the MANIFEST.MF file for the Portal.war file includes several JAR files that are located in the library directory within the EAR:

  Manifest-Version: 1.0
  Created-By: 1.3.0(SilverStream Software)
  Class-Path: library/PortalService.jar library/ContentMgmtService.jar library/FrameworkService.jar library/SecurityService.jar library/DirectoryService.jar library/UserService.jar library/WorkflowService.jar library/RuleService.jar library/DirectoryServiceRealm.jar library/xalan.jar library/xerces.jar

Classpath for Framework Director applications also maintain a simulated classpath for the Framework, which allows the classes in the Framework to find classes in the other subsystem JAR files that have been included with a particular Director EAR configuration. For more information about the simulated classpath, see About the subsystems.xml file and the simulated classpath.

Pieces of a Director application

The WAR files and JAR files in the Director EAR contain standard J2EE objects such as:

Servlets
JavaServer Pages (JSP pages)
Java utility classes
Custom tag libraries

In addition to these standard J2EE items, Director applications can also include these objects:

Object used in application	Description
PID pages	HTML or XML pages that contain Director components (defined by S3COMP tags) and therefore require processing by the Presentation Manager.
MyPortal pages	A customizable page that lets a user select the information that is of interest. These user-customizable pages are built with components. The Director environment provides layout tools so the administrator and end user can change the layout by adding and removing components.
Static pages	HTML pages that contain static content. These pages do not require the services of the Presentation Manager.
Components	Java classes that generate dynamic content. Most components use HTML or XML to present data to the user, but some components are nonvisual and therefore do not display data to the user. When a page is requested at runtime, the Presentation Manager gets the content from the components on the page and, if necessary, inserts the content into the page.
Style sheets (XSL)	Style sheets that transform XML pages into HTML (or some other output format). XSL is reusable for any page that uses the same XML elements.
Rules	Reusable logical formulas that you can apply to many business situations. Although the structure of a rule will look familiar to programmers, you need not be a programmer to use rules effectively. Rules consist of conditions and actions. If a group of conditions are true, then Director executes the associated actions. By defining rules for your application, you can modify the runtime behavior of your application to suit the personal profile of each user or to adapt to changing business conditions.
Workflow processes	Business procedures that together achieve an objective of the organization. Workflow processes use simple or rules-based routing (links) to move metadata and documents relating to an item of work from task to task (activities). Participants access their work at activities through workitem queues.
Resource descriptors	Other XML files that define various resources used by Director subsystems, such as portal categories, themes, layout definitions, and wireless device definitions.
Media	Images, sounds, and other media files required for the application.

Web tier WAR files

A Director EAR typically includes the WAR files that contain the administrative Web tiers:

WAR file	Description
PAC.war	Contains the PAC Web tier
PMC.war	Contains the PMC Web tier

Supporting WAR files

A Director EAR typically includes one or more of the following WAR files, which provide additional services:

WAR file	Description
Boot.war	Includes an autostart servlet that initiates the registration process for a Director application. The registration process loads configuration and service information for each subsystem included with the application.
Debug.war	Provides a simple reporting facility to help you troubleshoot deployed Director applications. The Debug.war is a utility WAR that is intended to be used during the process of developing and testing an application. It is not intended for deployment to a production environment.

Custom Web application (WAR) files

A Director EAR typically includes one or more WAR files that contain the code and resources for your application(s).

WAR file	Description
application.war	A WAR for the Java classes, JSP pages, and HTML pages that make up your application. Can contain: Resource set, which provides a repository of application-defined resources that interact with Director subsystems and dynamic loading capability for those resources Director portal functionality, which provides customizable pages and login support Selected component JARs For information about components provided with Director, see the chapter on installed components in Samples.

WAR file

Description

application.war

A WAR for the Java classes, JSP pages, and HTML pages that make up your application.

Can contain:

Resource set, which provides a repository of application-defined resources that interact with Director subsystems and dynamic loading capability for those resources
Director portal functionality, which provides customizable pages and login support
Selected component JARs

For more information For information about components provided with Director, see the chapter on installed components in Samples.

Subsystem archive files

Each Director subsystem has one or more archive files associated with it. The archive files conform to the following naming convention:

Subsystem archive file	Description
subsystem-nameService.jar	Contains the core business objects defining the subsystem, as well as any resource bundles required for internationalization. When you use the Director EAR project wizard to create a project, the subsystem-nameService.jar file for each selected subsystem is located in the library subdirectory of the EAR.
subsystem-nameService.war	Contains a Web representation of a subsystem. Unlike the Director Web tiers (PAC, PMC, and Portal), which provide a complete Web application that executes inside a Web browser, the subsystem WARs typically contain classes that provide basic services for the subsystem.
subsystem-name.war	Contains a Web tier. A Web tier is a prebuilt Web application.
subsystem-nameTag.jar	Contains a custom tag library that you can use in JSP pages in other Web tiers. A tag library has an associated TLD file that defines the available tags (methods) available to a JSP pages. The Director EAR Wizard does not add the tag library JAR files to your project automatically. To use a tag library JAR in your application, you need to use Workbench facilities to add the JAR and TLD to your application WAR. The tag library JAR files are installed in the utilities\Taglib subdirectory of your Director installation directory.
subsystem-nameEjb.jar	Provides EJB support for a subsystem. This JAR contains the server-side implementation required for EJB support. The Director EAR Wizard does not add the EJB JAR files to your project automatically. To use an EJB JAR in your application, you need to use Workbench facilities to add the JAR to your project. The EJB JAR files are installed in the templates\Director subdirectory of your Director installation directory.
subsystem-nameClient.jar	Contains the EJB client stubs and potentially the Web service stubs needed to access the core business objects contained within the core subsystem JAR (the subsystem-nameService.jar file). The Director EAR Wizard does not add the EJB client JAR files to your project automatically. To use an EJB client JAR in your application, you need to use Workbench facilities to add the JAR to your project. The client JAR files are installed in the templates\Director\library subdirectory of your Director installation directory.

Often a subsystem will be deployed in its entirety. However, Director allows you to deploy the archive files separately. For example, you might deploy the UserService.jar file without including the UserTag.jar, UserEjb.jar,and UserClient.jar files.

The following table indicates which archive files are available for each Director subsystem:

Subsystem	Service JAR	Service WAR	Web tier WAR	Tag library JAR & TLD	EJB JAR	Client JAR
Content Management	X	X		X	X
Debug			X
Directory	X				X	X
Framework	X			X
PAC			X
PMC			X
Portal	X		X	X
RSS	X
Rule	X			X
Search	X				X	X
Security	X				X	X
User	X				X	X
WebDAV		X
Workflow	X			X	X

Subsystem deployment dependencies

The following table outlines the interdependencies among the Director subsystems.

To use this subsystem	You need these subsystems	Additional notes
Content Management	Directory Framework Search Security User
Debug	Framework
Directory	Framework	The DirectoryServiceRealm.jar file is also required for the Directory subsystem. When you create a Director EAR project, this JAR file is automatically included in the /library directory of the project.
Framework	—
PAC	Directory Framework Portal Security User
PMC	Content Management Directory Framework Portal Security User
Portal	Directory Framework Security User
Rule	Directory Framework	PortalCA.jar provides conditions and actions related to resources in the Portal subsystem.
Search	Framework
Security	Directory Framework
User	Directory Framework Security
WebDAV	Content Management Directory Framework Security User
Workflow	Directory Framework Security	The Workflow subsystem is loosely coupled with the Rule subsystem. WorkflowAL.jar contains the classes for activities and links provided with Director.

Several additional archive files are required for the successful execution of Director applications. These are considered dependencies of all the major services:

jBroker-web.jar
Xalan.jar
xml-apis.jar
jakarta-regexp-1.2.jar

Like the DirectoryServiceRealm.jar, these modules are delivered in the /library directory of the Director EAR project. Most manifest files (META-INF/MANIFEST.MF) have these modules listed as dependencies.

The Director EAR Wizard and Setup Wizard enforce these dependencies. If you include a subsystem that depends on others, those other subsystems are also included in your project. If you try to remove a subsystem that others depend on, the Setup Wizard forces you to remove the dependent subsystems first before you can remove the subsystem they depend on.

How the subsystems register themselves with the framework

To make its services available, a subsystem must register itself with the framework. The process of self-registration involves loading configuration and service information into the framework. Once this information has been loaded, the appropriate factories can produce the correct implementations for each requested service. The registration process is initiated by the Boot servlet, which starts up automatically when you deploy a Director EAR or restart the application server. The Boot servlet is contained within the Boot.war file. It is an autostart servlet that must be the first servlet to load within a Director EAR.

Boot process During the framework boot process, the Boot servlet starts up the base factory for the framework, which performs these operations:

Reads the config.xml file for each subsystem into the framework's memory space.

The config.xml file sets the configuration properties for a subsystem. It is typically located in the subsystem-name-conf subdirectory of the subsystem-nameService.jar file for the subsystem. For example, the Portal subsystem has a config.xml file in the PortalService-conf subdirectory of the PortalService.jar file.

In the case of the Web tier WAR files, the config.xml is located in the conf subdirectory of WEB-INF.
Performs any database processing required for each subsystem. For each subsystem that needs to load data into a database, the base factory creates the schema and loads the data, if necessary.

Each subsystem that requires database processing delivers scripts for creating the schema and loading the data. These scripts are located in the database subdirectory of the subsystem-name-conf subdirectory of the subsystem-nameService.jar file for the subsystem. For example, the Directory subsystem includes several database scripts in the DirectoryService-conf subdirectory of the DirectoryService.jar file.

For more information about how the subsystems perform database processing, see How the subsystems access persistent data.
Reads the services.xml file for each subsystem into the framework's memory space.

The services.xml file sets properties for each of the services associated with a subsystem. It is located in the subsystem-name-conf subdirectory of the subsystem-nameService.jar file for the subsystem. For example, the Portal subsystem has a services.xml file in the PortalService-conf subdirectory of the PortalService.jar file.

In the case of the Web tier WAR files, the services.xml is located in the conf subdirectory of WEB-INF.
Notifies subsystem-specific service loaders that the main processing is done.
Starts all autostart services listed in services.xml files.

Autostart services have a startup property value of A (for automatic). Those services that have a startup element of M (for manual) are not started.

Messages during boot process Whenever you deploy a Director EAR or restart the application server, the server console prints out messages to inform you of the status of each step in the framework boot process:

  ###################################################################
  ###################################################################
  ###################################################################
  ### EboBaseFactory boot started
  ###################################################################
  ###################################################################
  ### EboBaseFactory add (config.xml) entries
  ###################################################################
  Loading ContentMgmtService-conf/config.xml
  Loading DirectoryService-conf/config.xml
  Loading FrameworkService-conf/config.xml
  Loading PortalService-conf/config.xml
  Loading RuleService-conf/config.xml
  Loading SearchService-conf/config.xml
  Loading SecurityService-conf/config.xml
  Loading UserService-conf/config.xml
  ###################################################################
  ### EboBaseFactory process db schema create/load
  ###################################################################
  Initializing log named EboFwLog at logging level 3 with separator |
  .....Adding log provider com.sssw.fw.log.EboStandardOutLoggingProvider to log EboFwLog
  Schema exists for ContentMgmtService subsystem.
  Schema exists for DirectoryService subsystem.
  Schema exists for SecurityService subsystem.
  Schema exists for UserService subsystem.
  ###################################################################
  ### EboBaseFactory notify custom db loaders
  ###################################################################
  ###################################################################
  ### EboBaseFactory add (services.xml) entries
  ###################################################################
  Loading ContentMgmtService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading DirectoryService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading FrameworkService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading PortalService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading RuleService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading SearchService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading SecurityService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  Loading UserService-conf/services.xml
          with factory loader com.sssw.fw.factory.EboFactoryLoader
  ###################################################################
  ### EboBaseFactory notify custom service loaders
  ###################################################################
  ###################################################################
  ### EboBaseFactory start auto-start services
  ###################################################################
  Auto Starting
       Interface : com.sssw.re.core.EboResourceListener
       Service : com.sssw.re.core.EboResourceListener
  Auto Starting
       Interface : com.sssw.fw.security.core.EboResourceListener
       Service : com.sssw.fw.security.core.EboResourceListener
  Initializing log named EboSecurityLog at logging level 3 with separator |
  .....Adding log provider com.sssw.fw.log.EboStandardOutLoggingProvider to log EboSecurityLog
  ###################################################################
  ### EboBaseFactory boot completed
  ###################################################################
  ###################################################################
  LicenseInfo: Type: User, Version: 4.0, User: Unlimited
  ###################################################################
  Initializing log named EboPortalLog at logging level 3 with separator |
  .....Adding log provider com.sssw.fw.log.EboStandardOutLoggingProvider to log EboPortalLog
       Loading resourceSet descriptor /WEB-INF/conf/resourceset.xml
       Loading ResourceSet ==> PAC-ResourceSet <==, dynamicClassLoading = false, verbose = false
       Loading resourceSet descriptor /WEB-INF/conf/resourceset.xml completed
       Loading resourceSet descriptor /WEB-INF/conf/resourceset.xml
       Loading ResourceSet ==> PMC-ResourceSet <==, dynamicClassLoading = false, verbose = false
       Loading resourceSet descriptor /WEB-INF/conf/resourceset.xml completed
       Loading resourceSet descriptor /WEB-INF/conf/resourceset.xml
       Loading ResourceSet ==> SilverTimes-ResourceSet <==, dynamicClassLoading = true, verbose = false
       Loading resourceSet descriptor /WEB-INF/conf/resourceset.xml completed

About the subsystems.xml file and the simulated classpath

In order to read the config.xml and services.xml files during the boot process, the Boot servlet uses information in subsystems.xml, a Framework configuration file, to build a simulated classpath. The simulated classpath also enables classes in Director JARs to find classes in other JARs.

Limitations to finding classes In a J2EE application, each WAR within an EAR has its own classpath as defined by the MANIFEST.MF file. In addition, the EAR itself has its own classpath, which is separate from the classpath for each of the WARs it contains. This presents a problem when two JARs located directly within an EAR are on the classpath specified for a WAR, and a class in one of the JARs needs to access a class in the other JAR. Since J2EE does not provide a mechanism for the JAR files to discover the classpath for the WAR, another mechanism is needed to provide the classpath. The Framework addresses this problem by maintaining a simulated classpath. The simulated classpath gives the classes in the framework a way to see which JAR files may have been specified in the MANIFEST.MF file for the Boot.war file.

Correspondence of actual and simulated classpaths The Framework uses the subsystems.xml file in the FrameworkService-conf directory to determine which JAR files to include in the simulated classpath. The subsystems.xml file lists the subsystems by name:

  <?xml version="1.0" encoding="UTF-8"?>
  <subsystems>
      <subsystem>ContentMgmtService</subsystem>
      <subsystem>DirectoryService</subsystem>
      <subsystem>FrameworkService</subsystem>
      <subsystem>PortalService</subsystem>
      <subsystem>RSSService</subsystem>
      <subsystem>RuleService</subsystem>
      <subsystem>SearchService</subsystem>
      <subsystem>SecurityService</subsystem>
      <subsystem>UserService</subsystem>
      <subsystem>WorkflowService</subsystem>
  </subsystems>

This list corresponds to the list of subsystem JAR files specified in the MANIFEST.MF file for the Boot.war:

  Manifest-Version: 1.0
  Created-By: 1.3.0(SilverStream Software)
  Class-Path: library/DirectoryServiceRealm.jar
              library/PortalCA.jar
              library/WorkflowAL.jar
              library/jakarta-regexp-1.2.jar
              library/jbroker-web.jar
              library/wasAuth.jar
              library/xalan.jar
              library/xml-apis.jar
              library/PortalService.jar
              library/DirectoryService.jar
              library/UserService.jar
              library/ContentMgmtService.jar
              library/FrameworkService.jar
              library/SecurityService.jar
              library/SearchService.jar
              library/RSSService.jar
              library/RuleService.jar
              library/WorkflowService.jar

Making sure the classpath is correct The subsystems.xml file lists the subsystems that may be in the classpath. If the subsystem names specified do not match the names specified in the MANIFEST.MF for the Boot.war file, the simulated classpath will not be correct. To ensure that it is correct, make sure the subsystem names specified in the subsystems.xml file exactly match the JAR file names for the subsystems specified in the MANIFEST.MF file for the Boot.war file.

How the subsystems access persistent data

The following subsystems depend on a database to store persistent information:

Content Management
Directory
Security
User
Workflow

After the Framework Boot servlet reads the config.xml file for each subsystem, it performs any database processing required for the subsystems. The Boot servlet checks the config.xml file to determine if it needs to create the schema and load data. It does this by examining the following configuration properties:

Property	Description
db-load-on-startup	Tells the Boot servlet to check the database to see if its schema was created previously. If the schema has not yet been created, it creates the schema automatically. If the schema has been created, it does not perform any database processing. This test ensures that the process of uploading the schema does not occur every time the server is started (or every time the EAR is deployed).
test-db-on-startup	Tells the boot servlet which table should be used to test for schema creation.

For example, the config.xml file for the Directory subsystem has these settings for the db-load-on-startup and test-db-on-startup properties:

  <property>
   <key>DirectoryService/db-load-on-startup</key>
   <value>true</value>
  </property>
  <property>
   <key>DirectoryService/test-db-on-startup</key>
   <value>AUTHGROUPS</value>
  </property>

When database processing is required for a subsystem, the boot servlet executes the scripts in the database subdirectory of the subsystem-name-conf subdirectory of the subsystem-nameService.jar file for the subsystem.

NOTE Do not edit the database scripts provided with the Director subsystems. These scripts should be used as is.

How the subsystems access application resources

Director subsystems often require access to application resources that are not stored in a database or defined in the configuration and service elements for the subsystems. Resource sets provide a known location for these resources. A resource set holds definitions for rules, portal components, styles, and various descriptors that implement features provided by Director subsystems. They can also hold Java classes and images for your application.

Resource sets are also a tool for streamlining development because they can be configured to load resources from disk as well as from a deployed JAR. This dynamic loading of resources allows you to modify and test changes without having to redeploy the whole Director EAR.

For more information Using the Resource Set in a Director Application describes how to use resource sets.

Core Development Guide