Custom Java in Oracle Utilities Cloud Services
Java is one of the supported extension technologies for on-premises implementations using the Oracle Utilities SDK to build and maintain Java code. Traditionally, the Oracle Utilities SDK also includes a set of utilities to transfer the extensions from the developer's environment to a target environment on-premises.
For customers with investments in existing Java-based extensions, the Oracle Utilities SDK and selected Oracle Utilities cloud services have been enhanced to allow the cloud as a target from the Oracle Utilities SDK to allow customers to transition to Oracle Utilities cloud services.
This sections provides details related to the migration of custom Java code to Oracle Utilities cloud services. This includes:
Restrictions
To allow the custom Java extensions to operate within Oracle Utilities cloud service the code must comply with the following:
• Oracle Utilities SDK Support:The java code must be developed using the Oracle Utilities SDK and the extraction utilities used to provide to the cloud.
• No Compiled Code: Only uncompiled code is accepted to be loaded onto Oracle Utilities cloud services to be assessed as part of the migration process and ongoing maintenance. Only source JAR files will be accepted as part of the process.
• No External Libraries: To ensure compliance and reduce risk, no third-party libraries, other than those provided by the service will be permitted.
• Code Location: The custom code must only exist in the com\splwg\cm\domain directory of the JAR file. No other directories or subdirectories are acceptable.
• Only Java Files are Accepted: Only .java files are accepted by the interface. All other file types are ignored and not uploaded into the service.
• Allow List Compliance: The Java code will be assessed against the Oracle Utilities cloud service and Oracle Cloud Infrastructure allow lists to ensure code is compliant with the cloud service. Code requiring direct access to memory, database, disk, or threads will not be permitted.
• Development Environments Only: The process used to transfer, verify, and build the deployment for the custom Java code can only be performed on development environments only. This feature is disabled, by default, in other non-production environments. This feature cannot be used on Production environments. It is expected to use Content Migration Assistant to migrate deployments across environments.
• Limited Scope for Change: In line with Oracle policy, the relative amount of change on the custom content is limited and is checked as part of compliance. This capability is a load and maintain capability only. It is not intended to allow continual extension of the product using Java, just to retain the investment in existing extensions. Partners and customers are expected to use existing cloud friendly capabilities to extend those services past the initial load and maintain levels.
Non-compliance with these restrictions or because of the compliance checking process will result in code being rejected by the Oracle Utilities cloud service and subject to remediation by partners and customers.
Code Migration Process
The cloud migration process has been designed to allow customers to reuse existing development tools and processes but use the cloud as the target environment. The process to migrate code is as follows:
• Develop Code: Using the Oracle Utilities SDK, develop Java code against a development version of the product. Once complete, use the SDK utilities as described in the SDK documentation to extract the source in a package for implementation on the cloud.
• Ad Hoc Generation Request: Upload the source using the provided REST API. This will upload the source to an isolated area within the service for use with the process. You must assign a Code Id which identifies the upload. The Code Id must only contain alphanumeric characters, dashes, or underscores. Credentials for the cloud service need to be provided with the command. The uploaded source is quarantined during the assessment process and assessed against several standards which include:
• Allow List Compliance: The code is assessed against classes and methods maintained for the Oracle Cloud Infrastructure. This assesses class usage to ensure manipulation of memory, network and file access are within tolerances.
Note: Refer to the Groovy class allow list for a list of the common classes available.
• Malicious Code Checks: The code will be checked for malicious code within tolerances set by the Oracle Cloud Infrastructure.
• Code Deployment Request: This step compiles and assembles the source code into the deployable module that is stored in the database ready for the deployment to the server. This also makes the deployment module available to be migrated using Content Migration Assistant (CMA) to make available to other environments.
• Deployment: This is the final step of the process that deploys the compiled code into the cloud infrastructure and made available to the service.
The diagram below illustrates the Java code migration and maintenance process.
Figure 3. Java Code migration/maintenance process
Upload and Process API
To upload the source JAR file the following command must be issued from your Oracle Utilities SDK client machine:
curl -F "codeClass=<class>" -F "sourceCodeContent=<source>" -i -X POST https://<serviceurl>/rest/customerCode/pushCustomerCode/<codeid> -u <user>:<password>
The parameters used in this command are as follows:
Additionally provide the following payload information:
Note: These parameters maybe provided in the REST client used to connect to the service or on the curl command line using the -F "<parameter>=value" option.
Preparing and Deploying
Once the code is uploaded and checked and verified, the next stage is to deploy the CM code into its isolated area and enable the new deployment. To do this:
• Run the K1-CSCPR job to deploy all the customizations in the PRIVILEGED threadpool . This must be performed after the Code Deployment Request has been successful. This process will deploy the customizations to the service.
Note: The PRIVILEGED threadpool is the only threadpool supporting Java deployment and can only run this process. Other processes cannot be run in this threadpool.
• Once the job has successfully completed, restart the CM servers where the deployment has occurred. This does not impact the non-CM severs. To do this, start the browser interface with the ?debug=true option as the suffix on the URL. Use the Restart CM Jar Servers to initiate the restart.
Advanced Operations
There are additional operations supported for Java developers that may be useful during development.
Downloading Generated Code from the Cloud
In most cases source code is housed in the Oracle Utilities SDK but it is also possible to get a copy of the generated code artifacts run on the cloud using the following command:
curl -x GET https://<serviceurl>/rest/customerCode/getGeneratedCustomerCode/<codeid> -u <userid>:<password> -J [-O]
Note: Use of the -O will output to stdout. Redirect to a file name to save locally.
The parameters used in this command are as follows:
Downloading API Jar files
It is possible to get a copy of the API Jar files used on the cloud using the following command:
curl -x GET https://<serviceurl>/rest/customerCode/getApiJars -u <userid>:<password> -J [-O]
Note: Use of the -O will output to stdout. Redirect to a file name to save locally.
The parameters used in this command are as follows:
Allow and No Allow List Of Java Classes
Oracle Utilities cloud service uses prebuilt allow lists to distinguish which classes that are permitted and not-permitted as part of the service. These lists are maintained by Oracle in conjunction with the Oracle Security team in line with Oracle Cloud policy. A full up to date list can be extracted using the API Jar files associated with your release of the service.
In general terms the following types of classes are automatically supported in the Oracle Utilities cloud services:
• Entity classes such as entity data transfer objects (DTO), id classes, language classes, language id classes, and collection classes.
• Lookups
• Algorithm Spot interfaces
• JOBOL record classes
Other classes will be available via the API Jar extract for reference purposes. Any class that is not listed is not available for use in the Oracle Utilities cloud services.
Note: These API's change regularly and therefore is it is recommended to be extracted on a regular basis.
Migration using Content Migration Assistant
After the deployment is built the compiled code and deployable can be migrated using the Content Migration Assistant (CMA) to your target environments.
It is highly recommended to use the Approve capability within Content Migration Assistant within the import process to manually review and approve changes before applying the change to the target environment. This provides a release approval step to implement fine grained control over change.
Note: After the migration has been applied, the deployment batch process and CM servers restarted must be executed to complete the implementation of the new release.