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.
• Allowlist Compliance: The Java code will be assessed against the Oracle Utilities cloud service and Oracle Cloud Infrastructure allowlists 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. The following additional requirements must be adhered to:
• Only code in the com/splwg/cm/domain namespace is permitted
• A manifest file should not be provided in the source JAR
• Ad Hoc Generation Request: Upload the source using the provided REST API. This will assess the source against the service. This can be used to assess the source prior to uploading to the service. 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 set to the "Generated" state if the assessment is successful. The source is assessed against several standards which include:
• Allowlist 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 allowlist 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 reassesses, 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. This step is independent of the Ad Hod Generation Request and loads the code into the cloud source repository. The Code Id used for this step must be unique for each upload.
• 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:
Parameter | Description |
|---|---|
<class> | Process to use for call: • K1GN - Adhoc Generation Request • K1DC - Code Deployment Request |
<source> | Provide the value "@cm.jar" |
<serviceurl> | Fully qualified URL for development environment to upload source to. Note: Only development environments can be used to upload source. This interface will not be available in non-development environments for security reasons. |
<codeid> | Code Identifier. The identifier must only contain alphanumerical, dashes, and underscores |
<userid> | User Id to use to connect to the cloud service |
<password> | Password for user to connect to the cloud service |
Additionally provide the following payload information:
Parameter | Comments |
|---|---|
sourceCodeContent | Upload the JAR file into this element using a REST client. |
commitReference | Commit reference from source control system used in Oracle Utilities SDK. • This should be provided for the initial Adhoc Generation Request (K1GN) to identify the source. • This is required for the Code Deployment Request (K1DC) to identify the source to process. |
branchName | Branch name where the code is to be deployed. Only the value main is supported at this time. |
changeReference | Optional. Change reference for traceability purposes only. This can be a release identifier for the custom code if necessary. |
comments | Optional. Additional comments to be attached to the upload for documentation purposes. |
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:
Parameter | Description |
|---|---|
<serviceurl> | Fully qualified URL for development environment to upload source to. Note: Only development environments can be used to upload source. This interface will not be available in non-development environments for security reasons. |
<codeid> | Code Identifier. The identifier must only contain alphanumerical, dashes, and underscores |
<userid> | User Id to use to connect to the cloud service |
<password> | Password for user to connect to the cloud service |
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:
Parameter | Description |
|---|---|
<serviceurl> | Fully qualified URL for development environment to upload source to. Note: Only development environments can be used to upload source. This interface will not be available in non-development environments for security reasons. |
<userid> | User Id to use to connect to the cloud service |
<password> | Password for user to connect to the cloud service |
Allow and No Allowlist Of Java Classes
Oracle Utilities cloud service uses prebuilt allowlists 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 and deployable code 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.