# How-To: Use Application Properties

Updates:

| $Date: 2006-08-09 19:30:52 -0700 (Wed, 09 Aug 2006) $
| $Author: sbutton $

- Introduction
- Prerequisites
  - What you need to know
  - Software requirements
  - Notations
- Building the Application
  - Looking up System Properties
  - Providing Application Properties
- Running the Application
  - Examining the Sample File Directories
  - Configuring the Environment
  - Starting the OC4J Instance
  - Generating, Compiling and Deploying the Application
  - Running the Application
  - Altering Application Properties at Deployment Time
  - Altering Application Properties Post Deployment
- Summary

# Introduction

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
- Sun JDK 1.5.0_07 or above, available here

### Notations

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

>     <%
>     String taxCode = System.getProperty("application.tax.code");
>     double taxRate = Double.valueOf(System.getProperty("application.tax.rate")).doubleValue();
>     ...
>     taxAdd = itemPrice * (taxRate /100);
>     totalPrice = itemPrice + taxAdd;
>     %>

### Providing System Properties

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.

> <orion-application>
> <property name="application.tax.rate" value="10" />
> <property name="application.tax.code" value="AU" />
> </orion-application>

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.

- OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall

### Generating, Compiling and Deploying the Application

To build the application, type the following command from the %HOWTO_HOME% directory:

>     > ant

>     Buildfile: 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.