Support has been introduced into OC4J 10g (10.1.3.1) to enable applications to provide properties (names, values) within an application deployment descriptor that are exposed automatically as System properties when the application is started and removed when the application is stopped. The properties are able to be accessed at runtime as regular System properties. During the deployment operation, the properties are able to be modified using the Deployment Plan Editor of Application Server Control (ASC). Post deployment, the properties are able to be viewed and manipulated using the MBean of the application.
Prerequisites
What
you need to know
Basic OC4J operation, application deployment processes, OC4J descriptor files, and System property access,
Software
Requirements
Provide links to where the
software is available. The least should include a JDK, Ant, and OC4J
OracleAS 10.1.3.1 is
installed, available from OTN
List the notation used
throughout the document. Keep to the convention of %NAME%
for environment like variables.
%ORACLE_HOME%
- the directory where Oracle Application
Server 10g (10.1.3) or OC4J is located
%JAVA_HOME%
- the directory where the JDK is installed
Building
the Application
This is a simple (very!) application which demonstrates accessing System properties that define a tax code and a tax rate for calculating the amount of sales tax due on a sale and the total price.
The application consists of a single JSP page which looks up the System properties and then uses the information to perform the calculations.
The System properties are specified as application properties on the deployed application. This is done using the orion-application.xml file which is embedded within the application archive.
Lookup System Properties
The index.jsp page looks up two System properties for use in its calculations
The System properties needed by this application are provided within its embedded orion-application.xml file. The <property> tag is used to specify a property which consists of a name and a value.
When the application is started, the properties specified in the orion-application.xml file will be added to the System property set. When the application is stopped, the properties will be removed.
Any changes made to the property names and/or values during the deployment process or via the Application MBean will be stored back in the orion-application.xml file of the application. This ensures the values are persisted across restarts and changes are maintained.
Running
the Application
This section can vary depend of
the fact that some how-to do not have any sample application distribute.
Examining
the Sample File Directories
Configuring
the Environment
Please check to make sure that the following properties are configured
correctly in the ant-oracle.properties
file located in the root of the sample's distribution (NOTE:
Some
of these properties will default to the values of corresponding
environment variables as noted below. If you have these
variables
setup in your environment you may not have to alter the values in the
file). If necessary, modify these variable to the proper
values
for you environment:
oracle.home
- the root
directory of oracle installation. Defaults to ORACLE_HOME environment
variable.
java.home -
the
root directory of JDK installation. Defaults to JAVA_HOME environment
variable.
oracleas.host
- the hostname
of the platform on which the OC4J instance is running.
Defaults
to localhost.
oracleas.http.port
- the port
on which the OC4J HTTP listener is listening. Defaults to
8888.
oracleas.admin.port
-
the port on which the OC4J administration processor is
listening.
Defaults to 23791.
oracleas.admin.user
- the
name of the OC4J administrator. Defaults to "oc4jadmin".
oracleas.admin.password
- the
password for the OC4J administrator. Defaults to "welcome".
oracleas.binding.module
- the
name of the HTTP web site to which the deployed application is
bound. Defaults to "default-web-site".
In addition, please make sure that the ant command associated with the
OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).
Configuring the Environment for a Managed OracleAS Instance
If you are running a managed version of the Oracle Application Server 10g, you are using OPMN, you must change the following values to match your configuration:
oracleas.http.port
- the port
on which the Oracle HTTP Server (OHS) is listening.
oracleas.admin.port
- The OPMN request port, as specified in opmn.xml, the default value is
6003. You can also check the OPMN request port using the
following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
oracleas.admin.user
- the
name of the OC4J administrator. Defaults to "oc4jadmin".
oracleas.deployer.uri
- the URI to use to do the different administration operation
(deployment, undeployment). The file contains different URI depending
of the topology of your application: stand alone OC4J, Managed Single
Node or Managed Cluster. You just need to un-comment the URI that
matches your topology.
oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed. Defaults to "home"
Starting
the OC4J Instance
Start an Oracle Application Server 10g (10.1.3) instance as follows:
Stand Alone Installation: %ORACLE_HOME%/bin/oc4j
start Note that the oc4j command
expects the JAVA_HOME environment variable to point to a full JDK
installation.
Generating,
Compiling and Deploying the Application
To build the application, type
the following command from the %HOWTO_HOME%
directory:
> antBuildfile: D:\myprojects\java\eclipse\workspace\how-to-applicationproperties\build.xml common: [echo] BuildName: how-to-applicationproperties [echo] BuildHome: D:\myprojects\java\eclipse\workspace\how-to-applicationproperties [echo] BuildFile: D:\myprojects\java\eclipse\workspace\how-to-applicationproperties\build.xml [echo] BuildJVM: 1.5 [echo] OracleHome: c:\java\oc4j-10131-dev init: [echo] -----> Initializing project properties setup: [echo] -----> Creating the required sub-directories [mkdir] Created dir: D:\myprojects\java\eclipse\workspace\how-to-applicationproperties\build\how-to-applicationproperties package-web: [war] Building war: D:\myprojects\java\eclipse\workspace\how-to-applicationproperties\build\how-to-applicationproperties\how-to-applicationproperties.war package-app: [ear] Building ear: D:\myprojects\java\eclipse\workspace\how-to-applicationproperties\build\how-to-applicationproperties.ear [copy] Copying 1 file to D:\myprojects\java\eclipse\workspace\how-to-applicationproperties\dist checkoc4javailable: [echo] ------> Checking to see if OC4J is available to deploy to [echo] Pinging localhost:23791 [echo] If OC4J is not started, please start it now. skipdeploy: deploy-ear: [echo] -----> Deploying the application module deployment (ear) file [echo] Target: deployer:oc4j:localhost:23791 [oracle:deploy] Deploying application how-to-applicationproperties. [oracle:deploy] 06/08/08 22:04:29 Notification ==>Uploading file how-to-applicationproperties.ear ... [oracle:deploy] 06/08/08 22:04:29 Notification ==>Application Deployer for how-to-applicationproperties STARTS. [oracle:deploy] 06/08/08 22:04:29 Notification ==>Undeploy previous deployment [oracle:deploy] 06/08/08 22:04:30 Notification ==>Initialize C:\java\oc4j-10131-dev\j2ee\home\applications\how-to-applicationproperties.ear begins... [oracle:deploy] 06/08/08 22:04:31 Notification ==>Initialize C:\java\oc4j-10131-dev\j2ee\home\applications\how-to-applicationproperties.ear ends... [oracle:deploy] 06/08/08 22:04:31 Notification ==>Starting application : how-to-applicationproperties [oracle:deploy] 06/08/08 22:04:31 Notification ==>Initializing ClassLoader(s) [oracle:deploy] 06/08/08 22:04:31 Notification ==>Initializing EJB container [oracle:deploy] 06/08/08 22:04:31 Notification ==>Loading connector(s) [oracle:deploy] 06/08/08 22:04:31 Notification ==>Starting up resource adapters [oracle:deploy] 06/08/08 22:04:31 Notification ==>Initializing EJB sessions [oracle:deploy] 06/08/08 22:04:31 Notification ==>Committing ClassLoader(s) [oracle:deploy] 06/08/08 22:04:31 Notification ==>Initialize how-to-applicationproperties begins... [oracle:deploy] 06/08/08 22:04:31 Notification ==>Initialize how-to-applicationproperties ends... [oracle:deploy] 06/08/08 22:04:31 Notification ==>Started application : how-to-applicationproperties [oracle:deploy] 06/08/08 22:04:31 Notification ==>Binding web application(s) to site default-web-site begins... [oracle:deploy] 06/08/08 22:04:31 Notification ==>Binding web application(s) to site default-web-site ends... [oracle:deploy] 06/08/08 22:04:31 Notification ==>Application Deployer for how-to-applicationproperties COMPLETES. Operation time: 1392 msecs [oracle:deploy] Application deployer for how-to-applicationproperties COMPLETES. deploy: [echo] -----> Deployed the application components required by OC4J for the execution of this application all: [echo] -----> Created all deployable units for the application BUILD SUCCESSFUL Total time: 7 seconds
You should now have the newly
created how-to-applicationproperties.ear
in your %HOWTO_HOME%/dist
directory.
This command will also
attempt to deploy the application if the build is successful. It will
first test whether the target OC4J is running before executing the deployment target.
Note that you can also deploy
the application separately . Ensure the %ORACLE_HOME%
environment variable is
defined and from the %HOWTO_HOME%
directory, type the
command:
>ant deploy ...
Running
the Application
Once deployed, the application is accessed from a Web browser using HTTP port of the default-web-site and a context-root of /how-to-applicationproperties.
1.
Access the application using http://host:port/how-to-applicationproperties
The TaxMan page will display.
Note the values shown for the Tax Code and Tax Rate fields -- these are supplied as Application Properties in the orion-application.xml file and inserted as System properties when the application is started.
2.
Enter an Item Price and calculate the total amount of money due.
Altering Application Properties at Deployment Time
Now that the basic operation of Application Properties has been observed, let's examine how the properties can be changed during the deployment operation and post deployment.
1.
Access Application Server Control using http://host:port/em
Logon as oc4jadmin user.
2.
Access the Applications Tab, select the how-to-applicationproperties item and click the Redeploy button
3.
Locate the how-to-applicationproperties.ear file in the %HOW-TO%\dist directory and click Next.
4.
Leave the default values and click Next
5.
Click the Edit Deployment Plan button to edit the deployment plan used when deploying the application.
6.
Scroll down the page and click the Edit properties link.
7.
The Application Properties defined within the orion-application.xml file are displayed.
Change the values to be
application.tax.rate 15
application.tax.code UK
Click Continue and complete the redeployment.
8.
Access the how-to-applicationproperties application again from a Web browser and notice the change that has occurred in the Tax Data shown.
Altering Application Properties Post Deployment
Once an application has been deployed, its Application Properties set can be altered using ASC and the System MBean browser.
1.
Access Application Server Control using http://host:port/em
Logon as oc4jadmin user if need be.
2.
Click the Applications tab to see the list of deployed applications
Click the how-to-applicationproperties link.
This will take you to the Application Home page of the how-to-applicationproperties application.
3.
Click the Administration tab to view the Administration tasks that can be performed on this application.
Click the Related System MBeans icon to view the System MBean browser focused at this applications MBeans.
4.
The System MBean Browser will render and highlight the J2EEApplication MBean for the how-to-applicationproperties application.
There are three tabs within the main frame to allow you to interact with the MBean -- Attributes, Operations and notifications.
5.
In the Attributes tab, scroll the page down until the properties attribute is visible.
6.
Click the properties link to see the current set of properties defined for the application.
The properties that you set during the deployment will be displayed.
7.
To set the properties with new values, you use the setProperty operation.
Click Return to return to the System MBean Browser page.
Click the Operations tab to view the list of Operations available on the MBean.
8.
Scroll the page down until the setProperty operation is visible.
Click on the setProperty link.
9.
Change the application.tax.code property by entering the property name and new value to set.
name: application.tax.code
value: NZ
Click the Invoke Operation button to set the property.
10.
Change the application.tax.rate property by entering the property name and new value to set.
name: application.tax.rate
value: 20
Click the Invoke Operation button to set the property.
Click the Return button to exit back to the main page.
11.
Go back to the Attributes tab and view the properties attribute again to verify the changes were made.
12.
Access the application and observe the changes that are now shown in the Tax Data settings.
13.
The changes made via the MBeans are persisted in the orion-application.xml file of the application so they are maintained across restarts of the application, and also able to be fetched and used as the default setting when the application is redeployed (if desired).
The persisted settings can be seen by looking at the orion-application.xml file in the %ORACLE_HOME%\j2ee\home\application-deployments\how-to-applicationproperties directory.
Summary
With OC4J 10g (10.1.3.1), applications are able to define properties consisting of name/value pairs, which are then set by the container as System properties when the application is started. The Application Properties are specified in a deployment descriptor and can be modified during the deployment process using ASC and its deployment plan editor, or post deployment using the MBean which is created for the application.
Bookmark
