Preparing Applications for Oracle Java Cloud Service

Understanding Application Library Behavior Changes on Oracle Cloud

Unless the Oracle Java Cloud Service - SaaS Extension documentation explicitly states changes to the original behavior of application libraries in order to be compatible with Oracle Java Cloud Service - SaaS Extension, then the application library's default behavior is not changed.

An example of a default application library behavioral change is the Log4j Console Appender, which has changed on Oracle Cloud. See Guidelines for Applications When Using Log4j Appenders.

An example of unchanged behavior is the setting of Log4j or JDK log levels using application code. These application libraries have not changed on Oracle Cloud, so they should work as they do in on-premise environments.

Frequently Asked Questions for Oracle Java Cloud Service - SaaS Extension is the only section of Using Oracle Java Cloud Service that provides examples for application libraries whose behavior does not change on Oracle Cloud.

Guidelines for Applications That Use a JDBC Data Source

The association of an Oracle Java Cloud Service - SaaS Extension instance with a Database Cloud Service instance makes the database instance available to deployed applications as a JDBC data source. By default, the JNDI name of the data source is the same name given to the Database Cloud Service instance at provisioning time. For example, if the name of the Database Cloud Service service instance is javatrial1801db, then the JNDI name of the Database Cloud Service instance will also be javatrial1801db.

If your application is using a JDBC data source for database access, then all references within the application to the assigned data source must be configured or modified to use either:

The JNDI name of the data source assigned within the Oracle Java Cloud Service - SaaS Extension instance.
A used-defined alias for the JNDI name of data source assigned within the Oracle Java Cloud Service - SaaS Extension instance.

Using a JNDI Alias for a JDBC Data Source

You can create an alias for the JNDI name of the JDBC data source assigned to your Oracle Java Cloud Service - SaaS Extension instance. Therefore, if your application is using a data source for database access, then all references to the data source can use the alias JNDI name instead of having to use the actual JNDI name of the data source.

For example, if the JNDI name of the Database Cloud Service instance is javatrial1801db, you can create an JNDI name alias for the data source named mycustomalias, and then just use mycustomalias in all references to the data source within the application.

Using an JNDI alias for a data source eliminates the need to update your applications if they need to be redeployed to another Oracle Java Cloud Service - SaaS Extension instance that is associated with a different Database Cloud Service. Instead, you only need to add same the JNDI alias referenced in your applications to the JDBC data source in the new Oracle Java Cloud Service - SaaS Extension instance.

Adding a JNDI Name Alias

You can create and manage JNDI name aliases for data sources using the javacloud.jar CLI in the Oracle Java Cloud Service - SaaS Extension SDK.

Here is an example of using the CLI to add a JNDI name alias for a data source:

$ ./javacloud -u username@oracle.com  -id usoracletrial08411 -si javatrial5334 -add-datasource-jndiname -jndiname mycustomalias

JNDI Name "mycustomalias" added to the data source : javatrial5334db

Here is an example of using the CLI to list your data source JNDI names:

$ ./javacloud -u username@oracle.com  -id usoracletrial08411 -si javatrial5334 -list-datasource-jndinames

#=============================#
| Listing 2 DS JNDI Alias(es) |
| [Identity                   |
| Domain=usoracletrial08411,  |
| Service                     |
| Instance=javatrial5334]     |
#====#===============#========#
|S.NO| Jndi Alias |ReadOnly   |
|====|===============|========|
|1 |javatrial5334db|true      |
|----+---------------+--------|
|2 |mycustomalias |false      |
+----+---------------+--------+

Guidelines for ADF Applications

Follow the guidelines in this topic whenever you use Oracle Java Cloud Service — SaaS Extension to deploy an ADF application.

If you are deploying an ADF application, you must configure or modify its weblogic.xml deployment descriptor to use the <exact-match> element, as described in the following example.

  <library-ref>
        <library-name>jsf</library-name>
        <specification-version>1.2</specification-version>
        <exact-match>true</exact-match>
    </library-ref>

Additionally, to ensure an adequate pool of database connections, set the following properties:

jbo.doconnectionpooling=true
jbo.txn.disconnect_level=1
jbo.ampool.doampooling=true

Note:

This library reference is added automatically if an ADF application is deployed from JDeveloper to a Cloud server, providing that the deployment profile is set to use "Oracle Cloud" as the platform, and as long as this library reference do not already exist in the weblogic.xml file.

If the application needs to be deployed to both on-premise environments as well as an Oracle Java Cloud Service - SaaS Extension instance, and if the on-premise environments use different role names and JDBC data source JNDI names, then use the WebLogic Server release 10.3.6 deployment plan feature when deploying the application to the on-premise environments. This approach will support the configuration differences between the on-premise environment and the Oracle Java Cloud Service - SaaS Extension instance.

To learn more about deployment descriptors, JDBC data sources, and deployment plans, see:

Note:

The following references pertain only to on-premises customers who need to use a deployment plan when their enterprise role names are different. Java Cloud Service - SaaS Extension does not support these deployment plans.

How to Create and Edit Deployment Descriptors in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
What You May Need to Know About JDBC Data Source for Oracle WebLogic Server in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
Using a Deployment Plan: Overview in Oracle Fusion Middleware Configuring and Using the Diagnostics Framework for Oracle WebLogic Server

Guidelines for Applications That Use Java EE or ADF Application Security

If an application uses Java EE or ADF application security for securing part or all of its pages (either programmatically or through its deployment descriptors), you must configure or modify the application to refer to the appropriate application roles.

The appropriate application roles are described in Securing Java EE Applications – Roles and Constraints and Securing ADF Applications – Roles and Constraints.

The current release of Oracle Java Cloud Service - SaaS Extension uses the second generation of the Identity Management System in Oracle Cloud. Therefore, applications that are deployed to the Oracle Java Cloud Service - SaaS Extension no longer need to prefix the principal name with the identity-domain-name when defining enterprise role policies in ADF or Java EE applications.

Required Changes to ADF Applications Using Role-based Security

For currently deployed ADF applications that use role-based security, you no longer need to prefix the principal-name with the identity-domain-name when defining enterprise roles in the jazn-data.xml deployment descriptor.

For role-based security with deployed ADF applications, you must either:

Modify the jazn-data.xml deployment descriptors by removing all identity-domain-name prefixing from the principal names.
If you cannot modify your deployment descriptors, use the Security page to append the identity domain name to the enterprise role so that it exactly matches the principal name in the jazn-data.xml file.

The following example shows how the jazn-data.xml deployment descriptor was typically configured for role-based security in previous releases of Oracle Java Cloud Service - SaaS Extension. Note that the identity domain name myidentitygroupfoo prefixes the eastcoastsales principle name.

...
          <app-role>
            <name>customer</name>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <name>myidentitygroupfoo.eastcoastsales</name>
                <class>weblogic.security.principal.WLSUserImpl</class>
              </member>
            </members>
          </app-role>
...

The following example shows how the jazn-data.xml deployment descriptor should be configured for role-based security in the current release of Oracle Java Cloud Service - SaaS Extension. Note that the eastcoastsales principle name is no longer prefixed by an identity-domain-name.

...
          <app-role>
            <name>customer</name>
            <class>oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <name>eastcoastsales</name>
                <class>weblogic.security.principal.WLSUserImpl</class>
              </member>
            </members>
          </app-role>
...

For more information, see Securing ADF Applications – Roles and Constraints.

Required Changes to Java EE Applications Using Role-based Security

For currently deployed Java EE applications that use role-based security, you no longer need to prefix the principal-name with the identity-domain-name when defining enterprise roles in the weblogic.xml deployment descriptor.

To use role-baseed security with currently deployed Java EE applications, you must either:

Modify the weblogic.xml deployment descriptors by removing all identity-domain-name prefixing from the principal names.
If you cannot modify your deployment descriptors, use the Security page to append the identity domain name to the enterprise role so that it exactly matches the principal name in the weblogic.xml file.

The following example shows how the weblogic.xml deployment descriptor was typically configured for role-based security in previous releases of Oracle Java Cloud Service - SaaS Extension. Note that the identity domain name myidentitygroupfoo prefixes the WestCoastSales principle name.

...
<wls:security-role-assignment>
<wls:role-name>sales</wls:role-name>
<wls:principal-name>myidentitygroupfoo.WestCoastSales</wls:principal-name>
</wls:security-role-assignment>
...

The following example shows how the weblogic.xml deployment descriptor should be configured for role-based security in the current release of Oracle Java Cloud Service - SaaS Extension. Note that the WestCoastSales principle name is no longer prefixed by an identity-domain-name.

...
<wls:security-role-assignment>
<wls:role-name>sales</wls:role-name>
<wls:principal-name>WestCoastSales</wls:principal-name>
</wls:security-role-assignment>
...

For more information, see Securing Java EE Applications – Roles and Constraints.

Guidelines for Applications When Accessing System Properties

You can access most system properties from application code by using getters and setters.

Examples of the system properties you can access (get or set) by using application code are:

Any custom properties. (That is, any properties not defined by WebLogic Server or Java EE.)
The following HTTP proxy properties are getable:
- http.proxyHost
- http.proxyPort
- https.proxyHost
- https.proxyPort
The following categories of system properties are not available to be either get or set. Attempting to do so will result in an access control exception.
- Java system properties related to the Java Security Manager.
- Java system properties related to WebLogic Server security.
- Java system properties related to the JVM specification.

Note:

All system properties that are set using application code in Oracle Java Cloud Service - SaaS Extension are not persisted when the service is restarted. Therefore, it is the responsibility of the application setting and getting them to persist them. A security exception will be raised if the application is trying access a property that is not allowed.

Guidelines for Applications When Using Log4j Appenders

The Oracle Java Cloud Service - SaaS Extension supports Log4j so deployed applications can use packaged Log4j libraries to log their messages. There are no limitations on the Log4j appender that is configured for applications, provided those appenders do not violate any security requirements.

Oracle recommends the two most commonly-used appenders:

ConsoleAppender – Logs that are written through this appender get redirected to the Oracle Java Cloud Service - SaaS Extension logs, which already contain JDK logs, along with certain WebLogic Server log messages. By using the ConsoleAppender, you can use the Oracle Java Cloud Service - SaaS Extension's CLI-based tools or the Oracle Java Cloud Service - SaaS Extension Control to query the service logs to find the Log4j logs as well.
FileAppender or any of its subclasses – The log files need to be written to a unique volume that can be read and written to, such as /customer/scratch/${weblogic.Name}/log4j.log, so that different managed servers do not end up using the same path. See Guidelines for Applications When Accessing a Local File System. The whitelist tool validates when the log4j.properties or log4j.xml configuration files are used to initialize Log4j. The whitelist will provide a warning if it cannot find the expected path for writing the logs.

This sample log4j.properties file shows the path where log files are written as /customer/scratch/${weblogic.Name}/log4j.log, which is inside the supported read/write area. It also shows how the dynamic portion ${weblogic.Name} ensures that each managed server finds a different path.

# Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
# Root logger option
log4j.rootLogger=ALL, file, out

# Direct log messages to a log file
log4j.appender.file=org.apache.log4j.RollingFileAppender
log4j.appender.file.file=/customer/scratch/${weblogic.Name}/log4j.log
log4j.appender.file.append=true
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n

# Direct log messages to stdout
log4j.appender.out=org.apache.log4j.ConsoleAppender
log4j.appender.out.layout=org.apache.log4j.PatternLayout
log4j.appender.out.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n

Note:

Oracle Cloud does not affect Log4j's mechanism for locating its own configuration files; therefore, the location of Log4j properties files should be by default found on the system CLASSPATH. Please refer to the Log4j documentation for configuration file information.

Guidelines for Applications When Accessing a Local File System

Oracle Java Cloud Service - SaaS Extension allows local file system access to deployed applications through standard java.io.File APIs. The root path on the local file system is /customer/scratch/, and under this directory deployed applications can freely read from and write to any necessary files, such as Log4j configuration files.

For guidelines, see Guidelines for Applications When Using Log4j Appenders.

You can get the value of your /customer/scratch/ directory by using the system property java.scratch.dir, as follows:

System.getProperty("java.scratch.dir")

To facilitate portability, your on-premise environment can use a different path for the same java.scratch.dir property. (See Guidelines for Applications When Accessing System Properties.)

The /customer/scratch volume is shared among all the managed servers in an Oracle Java Cloud Service - SaaS Extension instance; therefore, these managed server can see the same physical file with the same path. Therefore, the application code running from different managed servers can read the same file using the same path. However, if the application needs to write data to this volume, the application instances running in different managed servers need to find a unique path under the volume to write to.

To manage this, applications can read a dynamic {weblogic.Name} system property to get the name of the managed server and append this name with the volume to get a unique path for writing. For example, applications running on a managed server name myMS1, would be configured to write to a /customer/scratch/${weblogic.Name}/myMS1/ directory.

Note:

The Oracle Java Cloud Service - SaaS Extension SDK has a sample application named "File Browser" that can be used to manage all the files in your /customer/scratch/ directory. The sample application also shows how java.io.* APIs can be used to read and write files. See Accessing the Local File System.