Developing exteNd Director Applications
CHAPTER 2
This chapter explains how to create exteNd Director projects. It contains these sections:
Your work in exteNd Director is organized into projects. A project contains:
A set of JARs (the JARs included depend on your project configuration choices; for more information see Subsystem architecture)
A project file has an .SPF extension. A single SPF file can contain multiple components and resources of many different types.
You can learn more about projects in general in the chapter on projects and archives in Utility Tools.
Default project When you install exteNd Director, a default project called Express.spf is installed on your system and deployed to your server (for some installation types). This project is a complete, working application that you can use as a basis for building your own production portal.
For more information, see the chapter on the using the Express Portal in the Portal Guide.
exteNd Director provides wizards that build different types of projects. Choosing the right project type includes decisions and knowledge about the:
exteNd Director supports the following project types:
Project type |
Description |
Deployment considerations |
---|---|---|
Portlet application |
Choose this option when you want:
The Portlet Application Wizard creates:
|
Can be deployed in shared, nonshared library, and 3rd party JARs environments. When you run your portlets external to the portal, you can have one of these configurations:
or
|
For nonshared library and 3rd party JARs environments: |
||
Project |
Choose this option when you want: This wizard creates:
|
Supports shared, nonshared library, and 3rd party JARs environments. For shared library environments:
If this project includes portlets, they will be running local to the portal regardless of whether it is an EAR or WAR project. |
For nonshared library and 3rd party JAR environments:
|
To create a portlet application project, see Creating a portlet application project
To create an exteNd Director project, see Creating an exteNd Director project
Using views to what you're looking for You can use views to display personalized lists of items within an exteNd Director project. Views can be used to look at resources in a resource set, or at system configuration and service settings. exteNd Director ships with several predefined views and also allows you to define custom views to display project items that are of particular interest to you.
For information on using views to find items in an exteNd Director project, see Working with Views.
To create portlet application project:
Select the Director tab, choose Portlet Application, then click OK.
If you already have an EAR project open, the wizard asks if you want to add the new project to it. Choosing yes means that the wizard creates the new project within the existing project. Any portlets existing in or added to the portlet application project would run external to the portal.
Continue as described in Selecting the Web App WAR next.
Choose an existing WAR, click the ellipsis button and navigate to the disk location. Choose the WAR and click Open.
Create a new WAR, click Create WAR. Complete the New Project panel and click Finish.
For more information on the New Project panel, see the sections on creating projects and archives in Utility Tools.
Click Next to go to the next wizard panel. See Specifying the project and archive name next.
To specify the project and archive name:
On the Project Information panel, specify the following options:
The wizard generates an exteNd Directorenabled Web application WAR.
At the top level of the WAR you'll see the standard J2EE WEB-INF/lib folder. In the WEB-INF folder you'll see these important files:
In the conf folder in the WEB-INF folder, you'll see three important exteNd Director files:
For information about developing portlet applications, see the chapter on developing portal applications in the Portal Guide.
Continue as described in Specifying project information next.
To specify project information:
Complete the Project Information panel as follows:
TIP: If you fill in the text boxes in order, subsequent text boxes are filled in automatically with useful default values.
Project setting |
What to specify |
---|---|
Project Type |
Choose EAR or WAR. |
Project Name |
Specify the name you want to use for the project file (the .SPF extension is automatically appended). As you enter a project name, the archive name is filled in automatically. |
Project Location |
Specify a root directory for the project. The wizard copies files and subdirectories to this location. You can type a path and/or use the Browse button to select a directory location. The location doesn't have to exist. As you enter a project location, the archive location is filled in automatically. If you do not specify an absolute path, the wizard uses exteNd's tools\bin directory. |
Archive Name |
Specify the name of the archive file that will be generated. The .EAR or .WAR extension is automatically added, depending on the project type specified. The Navigation Pane's archive layout displays the archive name. You can keep the default archive name (which matches the project name) or enter a new one. |
Archive Location |
Specify a directory location for the project archive or accept the default (which is the Project Location). |
J2EE Version |
If your server supports J2EE 1.3, select J2EE 1.3; otherwise, select J2EE 1.2. NOTE: If you want to change the J2EE version of a project at a later time, see the chapter on how to handle J2EE versions in Utility Tools. |
If the directories you specified do not exist, the wizard offers to create each of them. Click Yes to confirm any new directories.
The next wizard panel displays. See Specifying the project setup next.
Complete the panel by choosing either Typical or Custom:
Click Next to go to the next wizard panel. See Specifying application options next.
To specify the application options:
On the Application Options panel, specify the following settings, then click Next:
Click Next to go to the next wizard panel:
If your project includes the Content Management subsystem, see Specifying the Content Management Search configuration
Otherwise, see Directory configuration.
The Content Management Search panel has three tabs: the Repository tab, the Synchronization tab, and the Filters tab.
To specify the Content Management Search configuration:
On the Repository tab, you can specify these settings:
On the Synchronization tab, you can specify these settings:
On the Filters tab, you can make this setting:
Click Next to go to the next wizard panel:
If you selected Typical setup, see Directory configuration.
If you selected Custom setup, see Content Management caching configuration next.
On the Content Management Caching Configuration panel, make the settings you want as follows:
Click Next to go to the next wizard panel. See Directory configuration next.
On the Directory Configuration panel, select a server-specific security realm.
The security realms are as follows:
TIP: If you have a user list from an earlier version of exteNd Director on the target server, select exteNd server (compatible).
Click Next to go to the next wizard panel:
If you chose an LDAP realm, you need to do more configuration; see LDAP realm configuration next.
Otherwise, see Framework configuration.
If you chose an LDAP realm, you need to specify your LDAP configuration options on the Directory Ldap Configuration panel.
LDAP configuration options are as follows:
To complete the Framework configuration:
On the Framework Configuration panel, specify values for these framework settings:
Framework option |
What to specify |
---|---|
Director Framework Datasource |
Specify the JNDI name for your application's database. The database contains exteNd Director application data such as content and user information. The value you specify depends on the target application server. For exteNd Application Servers
For application servers other than the exteNd Application Server Replace the suggested value with the JNDI name for the database. For example: for a data source named MyDB, specify MyDB. For any application server Typically you will not need to access the JNDI name directly in your applications. But if you need to do so, you can use the Framework API to get the property stored in the FrameworkService config.xml, as shown in this coding technique: // get an EbiConfig object com.sssw.fw.api.EbiConfig myconfig = com.sssw.fw.factory.EboFactory.getConfig(); // get value from the key in config.xml String dsname = myconfig.getProperty("com.sssw.fw.datasource.jndi-name"); // access the data source try{ javax.naming.InitialContext ctx = new javax.naming.InitialContext(); javax.sql.DataSource source = (javax.sql.DataSource)ctx.lookup(dsname); } catch(javax.naming.NamingException ne){} |
Locksmith |
To use ACL-based security, specify the user ID for administering security using the DAC. The ID you specify must exist in the server's authentication realm when you deploy the exteNd Director EAR or WAR. NOTE: If you do not want to use ACL-based security in your application, set the Locksmith to anonymous to prevent ACLs from being set up for the exteNd Director Admin elements.
|
Enable User Transaction Support? |
When checked, your application uses exteNd Director's transaction support. Uncheck this setting if you are deploying to an application server that does not provide JTA capabilities natively or through third-party extensions. |
Specify values for these cluster options:
Cluster option |
What to specify |
---|---|
Do you want to use clustering? |
Select Yes to enable exteNd Director support for clustering. The server you deploy to must already be set up as part of a server cluster. |
Host |
Specify the URL of the server that will run the exteNd Director Cache Coordinator.
NOTE: You must use the exteNd Director installation program to install the Cache Coordinator on the server. |
Port |
Specify the RMI port number that the Cache Coordinator will listen on. This must be the same value you specify when you install the Cache Coordinator. |
The Generated UID field displays an application identifier used for clustering. You cannot change it.
Specify a writable directory for exteNd Director use:
Click Next to go to the next wizard panel. See AES encryption key next.
exteNd Director encrypts portlet preferences in the database using a default key that is not unique. You can force the default key to be unique using the FIPS-approved AES encryption. If you require FIPS-compliant security for your application, it is recommended that you have your new projects generate a unique key.
On the AES Encryption Key panel, specify the following options:
Option |
Value |
---|---|
Generate New AES encryption key? |
When checked, the wizard generates a unique encryption key for the stored portlet preferences. Checking this generates a new encryption key file. |
Click Next to go to the next wizard panel:
If you selected an EAR, see LDAP user options next.
If you selected a WAR and an LDAP realm, see LDAP user options.
If you selected an LDAP realm, you need to specify your user options on the User Ldap Options panel.
The LDAP user options are as follows:
IMPORTANT: Before you deploy a project that uses an LDAP realm, you need to perform these configuration steps:
You can perform these steps after you complete the EAR Wizard.
For details, see the section on LDAP predeployment tasks (eDirectory only).
On the Summary panel, clear the Build project after wizard is finished check box if you don't want to build the project archives right away.
TIP: A recently built project is necessary for editing J2EE descriptor files and for deploying exteNd Director Web tier tools. You can let the wizard start the build process or you can select Build commands on the Project menu later.
Click Finish to create the project.
The wizard takes some time to copy the files to the project directory. Then it builds the project if you selected that option.
The Project Wizard generates a J2EE-compliant WAR or EAR (depending on your selection). The project contains the subsystem files needed for compile or runtime.
exteNd Director EAR project structure At the top level of an exteNd Director EAR project, you will see:
The EAR project contents include:
File |
Description |
---|---|
Portal WAR file |
Contains the JARs needed by the exteNd Director subsystems included in the project. |
ConfigService.jar |
Located in the \library folder. Contains configuration and service properties files for the project's subsystems.
|
JAR files |
Located in the \library folder. The set of JARs needed by your application for either compile or runtime services. In a shared library configuration, these service JAR files appear grayed out and in parentheses; they are available for compile-time use but are not included in the deployment archive. |
exteNd Director WAR project structure At the top level of an exteNd Director WAR project, you will see:
The WAR project contents include:
File |
Description |
---|---|
ConfigService.jar |
Located in the WEB-INF\lib folder. Contains configuration and service properties files for the project's subsystems.
|
JAR files |
Located in the WEB-INF\lib folder. The set of JARs needed by your application for either compile or runtime services. Files that are grayed out in the display are needed for compiile time only and are not deployed to the server. |
Configuration and service files Each exteNd Director subsystem relies on a configuration file and a services file. The files are stored in the ConfigService.jar.
EAR namespacing The J2EE specification does not require the EAR name to be part of the context for a WAR file. This can be a problem when multiple EAR files with similar content are deployed to the same server. For example: if you deploy the same WAR in several different EAR files to the same server, the application server will not be able to distinguish the different versions of the WAR. To solve this problem, exteNd Director introduces the notion of EAR namespacing. The namespace is part of the URL for accessing the exteNd Director Web tiers. exteNd Director prefaces the context for each WAR with the EAR name as the default namespace. The context for each WAR is specified in the application.xml file for the EAR.
NOTE: On a Novell exteNd Application Server: if you deploy to a database other than SilverMaster, the URL would also include the database name.
Classloading within an exteNd Director EAR 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. exteNd 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 JARsince 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.
Classpath for Framework exteNd 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 exteNd Director EAR configuration.
Each exteNd Director subsystem has one or more archive files associated with it. When you select a subsystem in the Project Wizard, the wizard adds the archives you need for the project type you're creating (EAR or WAR). In addition, the wizard automatically enforces any dependencies that exist for the subsystem. If for example you include a subsystem that depends on others, those other subsystems are also included in your project.
Subsystem archive naming conventions The subsystem archive files conform to the following naming convention:
Subsystem dependencies The Project Wizard and Setup Wizard enforce subsystem dependencies for nonshared library environments. 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. In a shared library environment, the wizard cannot enforce any dependencies.
The following table outlines the interdependencies among the exteNd Director subsystems:
Third-party archive files Several additional third-party archive files are required for the successful execution of exteNd Director applications. In a nonshared library environment, these modules are delivered in the /library directory of an exteNd Director EAR project (the WEB-INF\lib directory of a WAR project). Most manifest files (META-INF\MANIFEST.MF) have these modules listed as dependencies.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...