Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) Part Number B31074-05 |
|
|
View PDF |
This appendix explains how to manually package your portlet producer implementation into a portable format suitable for deployment on the Oracle Application Server or another J2EE application server. It then explains how to deploy the resulting EAR file in an Oracle Application Server environment and subsequently register it with one or more OracleAS Portal instances. The sections in this appendix are as follows:
Note:
In general, Oracle recommends that you package and deploy your producers using the tools available in Oracle JDeveloper. However, if you find that you must package and deploy your producers manually for some reason, then refer to the tasks in this appendix.Note:
Throughout this chapter, you will see references to ORACLE_HOME. ORACLE_HOME represents the full path of the Oracle home, and is used in cases where it is easy to determine which Oracle home is referenced. The following conventions are used in procedures where it is necessary to distinguish between the middle tier, OracleAS Infrastructure, or Oracle Application Server Metadata Repository Oracle home:MID_TIER_ORACLE_HOME, represents the full path of the middle-tier Oracle home.
INFRA_ORACLE_HOME, represents the full path of the Oracle Application Server Infrastructure Oracle home.
METADATA_REP_ORACLE_HOME, represents the full path of the OracleAS Infrastructure home containing the Oracle Application Server Metadata Repository.
Before preceding with packaging and deploying your producer, you must understand the following basic concepts:
WAR and EAR files are used to deploy applications on a J2EE application server, such as Oracle Application Server. The WAR and EAR files encapsulate all of the components necessary to run an application in a single file. These files make the deployment of an application very easy and consistent, reducing the possibility of errors when moving an application from development to test, and test to production.
WAR files represent a Web application and include all the components of that Web application, including Java libraries or classes, servlet definitions and parameter settings, JSP files, static HTML files, and any other required resources.
EAR files represent an enterprise application.
PDK-Java enables you to deploy multiple producers under a single adapter servlet. The producers are identified by a service identifier. When you deploy a new producer, you must assign a service identifier to the producer and use that service identifier when creating your producer WAR file. The service name is used to look up a file called service_id
.properties
, which defines the characteristics of the producer, such as whether to display its test page.
For example, you can register the PDK-Java samples producer using the following URL and a service identifier of urn:sample
:
http://mycompany.com/jpdk/providers
Alternatively, you can use a URL of the form:
http://mycompany.com/jpdk/providers/sample
where the producer name (sample) is appended to the URL of the PDK-Java samples producer. In this case, you should leave the Service Id field blank when registering the producer.
You can specify the service identifier separately in cases where multiple portals are sharing the same producer. By registering each portal with a different service identifier, you can specify the producer properties for each consumer independently.
Once your producer has been deployed, you must use the correct service identifier to register your producer with OracleAS Portal, which ensures that requests are routed to the correct producer. If the adapter servlet receives a request without a service identifier, then the request goes to the default producer.
Note:
If you do not know the service identifier, then check the producer test page or contact the administrator of the producer. If you are using the Federated Portal Adapter, then the URL points to the adapter, not the producer, thus you must enter a value for this field. In this case, the service identifier would beurn:
followed by the name of the database provider.The following sections show the steps you must perform to package and deploy a producer manually:
The steps in this section explain how to manually package a WAR file. If you are familiar with one of the various utilities for assembling WAR files, then you are free to assemble your WAR file that way.
In preparation for creating your WAR file, you must perform the following steps:
Create a working directory where you can collect the necessary files.
Extract the template.war
file from /pdk/jpdk/v2/template.war
into your working directory. Make sure that you extract the file paths, too.
If your producer needs any additional JAR files, then add them to the WEB-INF/lib
directory.
If your producer needs any additional Java classes not contained in a JAR file, then add them to the WEB-INF/classes
directory. Make sure that you save the class file in a directory structure that corresponds to their Java package names.
Add any static HTML files, JSPs and images to your working directory. Create subdirectories as needed to organize the files. Note that the subdirectories will become part of the path necessary to access the HTML or JSP files.
Create a subdirectory for your producer under the producers directory.
Copy the _default.properties
file to service_name
.properties
and edit it to reflect your producer's configuration.
Set the definition
value in the provider_name
.properties
file that is available in the WEB-INF/deployment
folder, as follows:
definition=providers/provider_dir_you_created/provider.xml
Place your producer definition file in the subdirectory you just created.
Edit _default.properties
to reflect the configuration settings of your default producer. The default producer is accessed if a service identifier is not specified in a request. See Section D.2.1.2, "Specifying Your Default Service" for more information about this step.
If you use servlets to render content, then edit WEB-INF/web.xml
to add your servlets to the list of predefined servlets. Be careful not to remove the entries for servlets required by PDK-Java.
The default service is the producer that receives any request without a service name. You specify a default producer by editing the _default.properties
file in the deployment directory of your WAR file.
Edit the definition entry to point to the producer definition file that represents your default producer. Paths should be relative to the WEB-INF directory within your WAR file, not the physical location of the file in the file system.
The _default.properties
file looks similar to the following:
serviceClass=oracle.webdb.provider.v2.adapter.soapV1.ProviderAdapter
loaderClass=oracle.portal.provider.v2.http.DefaultProviderLoader
showTestPage=true
definition=providers/sample/provider.xml
autoReload=true
Once you have specified the contents of your WAR file, you are ready to create the WAR file itself. To create the WAR file, perform the following steps:
Zip the contents of the working directory you created in Section D.2.1.1, "Preparing Your Directories", including the subdirectory paths but not the working directory path itself.
Rename the resulting file to give it a meaningful name and change the extension to .war
.
To create the EAR file manually, perform the following steps:
Create another working directory for the creation of your EAR file.
Extract the template.ear
file from /pdk/jpdk/v2/template.ear
into your working directory. Make sure that you extract the file paths, too.
Open the META-INF/application.xml
file that was contained in the template EAR file. It should look something like the following:
<?xml version "1.0"> <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc. //DTD J2EE Application 1.3//EN" "http://java.sun.com/j2ee/dtds/application_1_3.dtd"> <application> <display-name>Display Name of the Application</display-name> <description>Description of the application</description> <module> <web> <web-uri>yourwarfile.war</web-uri> <context-root>/</context-root> </web> </module> </application>
Table D-1 describes the elements of application.xml
.
Table D-1 Elements of application.xml
Element | Description |
---|---|
<display-name> |
Is the name of the application. |
<description> |
Is a description of the application and its functions. |
<web-uri> |
Is the name of your WAR file. |
<context-root> |
Is the prefix you would like to map to your application by default (for example, |
Save application.xml
back to the same location without changing the name of the file.
Copy the WAR file you created earlier into your working directory. Put it in the working directory itself, not a subdirectory.
Zip the contents of the working directory, including the subdirectory paths but not the working directory path itself.
Rename the resulting file to give it a meaningful name and change the extension to .ear
.
You can deploy your EAR file in any of the following ways depending upon your requirements:
To deploy your EAR file using the Grid Control Console, you must have PDK-Java installed in your target OC4J. To deploy your EAR file using this method, perform the following steps:
Start the Grid Control Console and navigate to the home page of the OC4J instance in which you configured PDK-Java (for example, OC4J_Portal
).
On the Applications tab, click Deploy EAR file.
Enter the information in Table D-2.
Click Continue. The URL mapping for Web Modules appears. The mappings will default to the context roots specified in application.xml
(for example, /myapp
), but you can change them to avoid clashing with the context roots of other deployed applications.
Click Finish. A summary appears with all of the information you entered.
Click Deploy.
Click OK.
Your producer application is now deployed to your Oracle Application Server instance. You should see the newly deployed application in the list of applications for the selected OC4J instance. Once you have successfully deployed your EAR file, you must test the deployment. See Section D.2.3, "Testing Deployment".
To deploy your EAR file using dcmctl
, you must have PDK-Java installed in your target OC4J.
Note:
Before usingdcmctl
to manage an Oracle Application Server instance, make sure you have no Grid Control Console processes managing that same instance. If multiple processes manage the same instance, then you run the risk of inconsistencies or corruption in the data used to manage the instance.You deploy your EAR file using the command-line deployment utility dcmctl
: (Arguments in brackets are optional.)
cd MID_TIER_ORACLE_HOME/dcm/bin/ ./dcmctl deployApplication -f file -a app_name [-co comp_name] [-enableIIOP] [-rc rootcontext] [-pa parent_name]
where:
file
is the name of the EAR or WAR file you want to deploy.
app_name
is the name of the application specified by the user in the original deployment.
comp_name
is the name of the OC4J instance to which the application will be deployed. The default is the home instance. (Optional)
enable IIOP
enables the Internet Inter-Orb Protocol. (Optional)
rootcontext
is the base path used in the URL to access the Web module (for example, http://hostname:port/context root
). This option applies only to the deployment of WAR files. (Optional)
parent_name
is the parent application name. The parent application contains common classes used by child applications. (Optional)
Your producer application is now deployed to your Oracle Application Server instance. Once you have successfully deployed your EAR file, you must test the deployment. See Section D.2.3, "Testing Deployment".
To deploy your EAR file to a standalone instance of OC4J, it must be a compatible version and have PDK-Java installed. To deploy your EAR file in this method, perform the following steps:
If OC4J is not already running, then start it as a background process with the following commands:
On Microsoft Windows:
cd OC4j_HOME\j2ee\home start java -server -Xmx256m -jar oc4j.jar
On UNIX/Linux (Bourne shell):
cd OC4J_HOME/j2ee/home java -server -Xmx256m -jar oc4j.jar &
where:
OC4J_HOME
is your OC4J installation root directory (for example, D:\oc4j904
).
Note:
The-Xmx256m
option specifies a maximum heap size of 256 Mb for the OC4J process, which is the recommended setting. You can raise or lower this setting to suit your application. If you encounter java.lang.OutOfMemoryError
exceptions, then you should raise this setting.Deploy your EAR file using the following command:
java -jar admin.jar ormi://localhost admin admin_password -deploy -deploymentName application_name -file ear_file_path
where:
admin_password
is the OC4J administration password you set on installation.
application_name
is the unique name given to the application for administrative purposes.
ear_file_path
is the full path to your EAR file on the file system.
For each of the WAR files in your EAR file (as listed in OC4J_HOME/j2ee/home/applications/
application_name
/application.xml
), bind the corresponding Web applications to a URI path on your Web site with the following command:
java -jar admin.jar ormi://localhost admin admin_password -bindWebApp application_name web_app_name file:OC4J_HOME/j2ee/home/config/default-web-site.xml context_root
where:
web_app_name
is WAR file name without the .war
extension (for example, jpdk
).
context_root
is the URI path prefix you would like to be mapped to that Web application (for example, /myapp
).
Your producer application is now deployed to your Oracle Application Server instance. Once you have successfully deployed your EAR file, you must test the deployment. See Section D.2.3, "Testing Deployment".
To test your producer deployment, you access the producer test page with a URL of the following form:
http://host:port/context_root/providers
where:
host
and port
are the host name and port number of the HTTP listener for your target OC4J instance. In an Oracle Application Server installation with Oracle Web Cache installed, port
should be the Oracle Web Cache listener port (for example, 7777). In a standalone OC4J installation, the default HTTP port number is 8888.
context_root
is the URI path prefix you mapped to the producer Web application on deployment (for example, /myapp
) or the default one specified in application.xml
in a manual deployment with dcmctl
.
For example:
http://my.host.com:7777/newProvider/providers
If your .properties
file specifies showTestPage=true
, then you should see the familiar test page for your default producer. To view the test page for a specific producer service, you can append the service name to the URL. For example:
http://my.host.com:7777/newProvider/providers/myService
In PDK-Java, you can specify a number of deployment properties through JNDI variables. Table D-3 provides a list of these variables with descriptions.
Table D-3 JNDI Variables for Producer Deployment
Variable | Description |
---|---|
oracle/portal/provider/global/log/logLevel |
Is the logging level (0-8) used by PDK-Java and applies to all producers. |
oracle/portal/service_name/showTestPage
|
Is a Boolean flag that specifies whether a producer's test page is accessible. The default value is true. |
oracle/portal/service_name/maxTimeDifference
|
Is the producer's HMAC time difference. |
oracle/portal/service_name/definition
|
Is the location of the producer's definition file, |
oracle/portal/service_name/autoReload
|
Is a Boolean auto reload flag. The default value is true. |
oracle/portal/service_name/sharedKey
|
Is the HMAC shared key. It has no default value. |
oracle/portal/service_name/rootDirectory
|
Is the location for producer customizations. It has no default value. |
Setting the Variables
You can set the values of the variables in Table D-3 as you would any other JNDI variables. See Section 19.2.3.2, "Setting JNDI Variable Values" for information about how to set JNDI variables.
When using the PDK-Java framework in a production environment, you should secure your producers. See Chapter 10, "Securing Your WebCenter Application" for more information about securing producers.
Once you have successfully deployed and verified your producer, you can register it as you would any other producer. See Section 18.10, "Registering and Viewing Your Portlet" for more information about registering your producer.