Configuration
This topic provides details on compatibility, advanced configurations, and add-ons for the Oracle Cloud Infrastructure SDK for Java.
This topic provides details on compatibility, advanced configurations, and add-ons for the Oracle Cloud Infrastructure SDK for Java.
Security Manager Permissions
If your application needs to run inside the Java Security Manager, you must grant additional permissions by updating a policy file, or by specifying an additional or a different policy file at runtime.
The SDK requires the following permissions:
-
Required by Jersey:
permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; permission java.lang.RuntimePermission "accessDeclaredMembers"; permission java.util.PropertyPermission "*", "read,write"; permission java.lang.RuntimePermission "setFactory";
-
Required by the SDK to overwrite reserved headers:
permission java.util.PropertyPermission "sun.net.http.allowRestrictedHeaders", "write";
-
Required by the SDK to open socket connections:
permission java.net.SocketPermission "*", "connect";
To include another policy file, in addition to Java Runtime Environment's default policy file, launch the Java Virtual Machine with:
java -Djava.security.manager -Djava.security.policy=</path/to/other_policy>
To replace the default policy file, launch the Java Virtual Machine with:
java -Djava.security.manager -Djava.security.policy==</path/to/other_policy>
Use a single equals sign (=) when supplying an additional policy file. Use a double equals sign (==) only if you wish to replace the default policy file.
Java Virtual Machine TTL for DNS Name Lookups
The Java Virtual Machine (JVM) caches DNS responses from lookups for a set amount of time, called time-to-live (TTL). This ensures faster response time in code that requires frequent name resolution.
The JVM uses the networkaddress.cache.ttl property to specify the caching policy for DNS name lookups. The value is an integer that represents the number of seconds to cache the successful lookup. The default value for many JVMs, -1
, indicates that the lookup should be cached forever.
Because resources in Oracle Cloud Infrastructure use DNS names that can change, we recommend that you change the TTL value to 60 seconds. This ensures that the new IP address for the resource is returned on next DNS query. You can change this value globally or specifically for your application:
-
To set TTL globally for all applications using the JVM, add the following in the
$JAVA_HOME/jre/lib/security/java.security
file:networkaddress.cache.ttl=60
-
To set TTL only for your application, set the following in your application's initialization code:
java.security.Security.setProperty("networkaddress.cache.ttl" , "60");
Using the Jersey Default HttpUrlConnectorProvider
Starting with version 2.0.0, the SDK for Java supports using the Jersey
ApacheConnectorProvider
instead of the Jersey default
HttpUrlConnectorProvider
to allow the Apache HttpClient to make OCI
service calls.
To change to the Jersey default connector at the client level
At the client level, the SDK provides the following way to switch back to the old Jersey default connector:
ObjectStorageClient nonBufferingObjectStorageClient = ObjectStorageClient
.builder()
.clientConfigurator(builder -> {
builder.property(JerseyClientProperties.USE_APACHE_CONNECTOR, false);
})
// ...
.build(provider);
Overriding the
clientConfigurator
property of the client will revert back to the Jersey defaults. For configuring clientConfigurator
with the use of Apache Connector, use additionalClientConfigurator
or additionalClientConfigurators
.To change to the Jersey default connector at the global level
You can exclude the Apache HttpClient dependencies or use an environment variable. Excluding HttpClient DependenciesIf you are managing dependencies yourself:
- Remove the
org.apache.httpcomponents.httpclient
andorg.glassfish.jersey.connectors.jersey-apache-connector
JARs from the classpath
If you are using Maven to manage your dependencies:
- Add exclusions for the
org.apache.httpcomponents.httpclient
andorg.glassfish.jersey.connectors.jersey-apache-connector
dependencies.-
To add an exclusion if you use Jersey 2:
<dependencies> ... <dependency> <groupId>com.oracle.oci.sdk</groupId> <artifactId>oci-java-sdk-common-httpclient-jersey</artifactId> <version>...</version> <exclusions> <exclusion> <groupId>org.glassfish.jersey.connectors</groupId> <artifactId>jersey-apache-connector</artifactId> </exclusion> <exclusion> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> </exclusion> </exclusions> </dependency> ... <dependencies>
-
To add an exclusion if you use Jersey 3:
<dependencies> ... <dependency> <groupId>com.oracle.oci.sdk</groupId> <artifactId>oci-java-sdk-common-httpclient-jersey3</artifactId> <version>...</version> <exclusions> <exclusion> <groupId>org.glassfish.jersey.connectors</groupId> <artifactId>jersey-apache-connector</artifactId> </exclusion> <exclusion> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> </exclusion> </exclusions> </dependency> ... <dependencies>
-
The SDK for Java provides an environment variable to switch back to the old Jersey default connector at the global level. Set the value of the OCI_JAVASDK_JERSEY_CLIENT_DEFAULT_CONNECTOR_ENABLED
environment variable to true
. By default, this value is set to false
.
Switching off auto-close of streams
For API calls that return binary/stream response, the SDK will auto-close the stream once the stream has been completely read. This is because the SDK for Java supports the Apache Connector for sending requests and managing connections to the service. By default, the Apache Connector supports connection pooling. In the cases where the stream from the response is not closed, the connections don't get released from the connection pool.
To disable the auto-close behavior, call
ResponseHelper.shouldAutoCloseResponseInputStream(false)
.
Choosing connection closing strategies with the Apache Connector to optimize performance
The Apache Connector supports of two connection closing strategies:
ApacheConnectionClosingStrategy.GracefulClosingStrategy
and
ApacheConnectionClosingStrategy.ImmediateClosingStrategy
.
When using ApacheConnectionClosingStrategy.GracefulClosingStrategy
,
streams returned from a response are read until the end of the stream when closing
the stream. This can introduce additional time when closing the stream with a
partial read, depending on how large the remaining stream is. To avoid this delay,
consider using
ApacheConnectionClosingStrategy.ImmediateClosingStrategy
for
large files with partial reads. Note that
ApacheConnectionClosingStrategy.ImmediateClosingStrategy
takes
longer when using partial read for smaller stream size (streams smaller than 1MB).
If these Apache Connection closing strategies do not give you optimal results for your use cases, you can switch back to Jersey Default
HttpUrlConnectorProvider
using the method stated above.For more information, see: https://github.com/oracle/oci-java-sdk/blob/master/ApacheConnector-README.md.
Using BC-FIPS Instead of Bouncy Castle
If you need FIPS compliance, you must download and use a FIPS-certified version. The SDK supports bc-fips 1.0.2 and bcpkix-fips 1.0.3. You can download them at: https://www.bouncycastle.org/fips-java/
For help installing and configuring Bouncy Castle FIPS, see "BC FIPS Documentation" in the User Guides and Security Policy of the Bouncy Castle Documentation.
Self-Managed Dependencies
If you are managing dependencies yourself:
- Remove the non-FIPS Bouncy Castle jar files from the class path:
bcprov-jdk15on-1.60.jar
bcpkix-jdk15on-1.60.jar
- Add the FIPS Bouncy Castle jar files to the class path instead:
bc-fips-1.0.2.jar
bcpkix-fips-1.0.3.jar
Maven-Managed Dependencies
If you are using Maven to manage your dependencies:
- Add the correct versions of
bc-fips
andbcpkix-fips
to your dependencies:<dependencies> . . . <dependency> <groupId>bc-fips</groupId> <artifactId>bc-fips</artifactId> <version>1.0.2</version> </dependency> <dependency> <groupId>bcpkix-fips</groupId> <artifactId>bcpkix-fips</artifactId> <version>1.0.3</version> </dependency> . . . </dependencies>
- Since you are depending on an
oci-java-sdk*
package, you need to remove the non-FIPS Bouncy Castle dependencies:<dependencies> . . . <dependency> <groupId>com.oracle.oci.sdk</groupId> <artifactId>oci-java-sdk-common</artifactId> <version> . . . </version> <exclusions> <exclusion> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15on</artifactId> </exclusion> <exclusion> <groupId>org.bouncycastle</groupId> <artifactId>bcpkix-jdk15on</artifactId> </exclusion> </exclusions> </dependency> . . . </dependencies>
Using Your Own JAX-RS Implementation
The SDK for Java is bundled with Jersey, but you can also use your own JAX-RS implementation.
RESTEasy Client Configurator Add-On
The oci-java-sdk-addons-resteasy-client-configurator
is provided to demonstrate how to configure an alternate JAX-RS implementation. The add-on can be found in the bmc-addons
directory of the SDK.
For details on installation and configuration, see the Readme for the add-on.
For code samples that demonstrate how to configure the client, see:
Using SLF4J for Logging
Logging in the SDK is done through SLF4J. SLF4J is a logging abstraction that allows the use of a user-supplied logging library (e.g., log4j). For more information, see the SLF4J manual.
The following is an example that enables basic logging to standard out. More advanced logging options can be configured by using the log4j binding.
- Download the SLF4J Simple binding jar: SLF4J Simple Binding
- Add the jar to your classpath (e.g., add it to the
/third-party/lib
directory of the SDK download) - Add the following VM arg to enable debug level logging (by default, info level is used):
-Dorg.slf4j.simpleLogger.defaultLogLevel=debug