Skip to content

Commit 7aa56bf

Browse files
VidhiBhansaliVidhiBhansali
authored
Releasing version 2.0.0
Releasing version 2.0.0
2 parents 907b4cc + c45baca commit 7aa56bf

File tree

472 files changed

+16295
-953
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

472 files changed

+16295
-953
lines changed

‎ApacheConnector-README.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Apache Connector
2+
3+
The Java SDK now by default uses the `ApacheConnector` instead of the Jersey default `HttpUrlConnector` to send requests to the service.
4+
5+
Note: The `ApacheConfigurator` buffers requests into memory and can impact memory utilization of your application. This increased use of memory is especially relavent when using`ObjectStorageClient` to upload large objects to the Object Storage service.
6+
In order to prevent buffering of requests in memory please use `ApacheConfigurator.NonBuffering` and provide the `contentLength` when calling the api. For example, when calling `ObjectStorageClient.putObject()`, pass the content length when creating
7+
`PutObjectRequest`. For `ObjectStorageClient`, `ApacheConfigurator.NonBuffering` is the default option. Overriding the
8+
`clientConfigurator` will default back to Jersey Default Connector.
9+
10+
## Switching to Jersey Default HttpUrlConnectorProvider
11+
12+
The SDK for Java (starting versions 2.0.0) supports Jersey `ApacheConnectorProvider` by default instead of Jersey default `HttpUrlConnectorProvider`. This is to enable the support for the Apache HttpClient for making service calls. For customers who would like to switch back to the old Jersey default client, we provide an option to do so.
13+
14+
Note : Overriding the `clientConfigurator` property of the client will default back to the Jersey defaults. For configuring `clientConfigurator` with the use of Apache Connector, please use `additionalClientConfigurator`/`additionalClientConfigurators`.
15+
16+
There are multiple ways to configure this option depending upon the global/client level. This can be achieved by the following ways :
17+
18+
At the client level, the SDK provides the following way to switch back to the old Jersey default connector:
19+
20+
For clients that do not buffer requests into memory:
21+
22+
```
23+
IdentityClient.builder().clientConfigurator(new JerseyDefaultConnectorConfigurator.NonBuffering())
24+
```
25+
26+
For clients that buffer requests into memory:
27+
28+
```
29+
IdentityClient.builder().clientConfigurator(new JerseyDefaultConnectorConfigurator())
30+
```
31+
32+
At the global level, the SDK for Java provides the following way to switch back to the old Jersey default Connector :
33+
34+
Alternatively, this can be achieved by excluding the Apache HttpClient dependencies OR via an environment variable. Please follow the steps below.
35+
36+
### Self-Managed Dependencies
37+
38+
If you are managing dependencies yourself:
39+
40+
1. Remove the `org.apache.httpcomponents.httpclient` and `org.glassfish.jersey.connectors.jersey-apache-connector` JARs from the classpath
41+
42+
### Maven-Managed Dependencies
43+
44+
If you are using Maven to manage your dependencies:
45+
46+
1. Add exclusion for the `org.apache.httpcomponents.httpclient` and `org.glassfish.jersey.connectors.jersey-apache-connector` dependencies
47+
48+
<dependencies>
49+
...
50+
<dependency>
51+
<groupId>com.oracle.oci.sdk</groupId>
52+
<artifactId>oci-java-sdk-common</artifactId>
53+
<version>...</version>
54+
<exclusions>
55+
<exclusion>
56+
<groupId>org.glassfish.jersey.connectors</groupId>
57+
<artifactId>jersey-apache-connector</artifactId>
58+
</exclusion>
59+
<exclusion>
60+
<groupId>org.apache.httpcomponents</groupId>
61+
<artifactId>httpclient</artifactId>
62+
</exclusion>
63+
</exclusions>
64+
</dependency>
65+
...
66+
<dependencies>
67+
68+
### Switching back via environment variable
69+
70+
The SDK for Java also provides an environment variable to switch back to the old Jersey Default Connector at the global level. To achieve the same, please set the value of the environment variable - `OCI_JAVASDK_JERSEY_CLIENT_DEFAULT_CONNECTOR_ENABLED` to true. By default, this value is set as false.
71+
72+
### Switching off auto-close of streams
73+
74+
For API calls that return binary/stream response, the SDK will auto-close the stream once the stream has been completely read by the customer. If reading the stream completely, the SDK will automatically try to close the stream to release the connection from the connection pool, to disable this feature of auto-closing streams on full read, please call `ResponseHelper.shouldAutoCloseResponseInputStream(false)`. 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 and in the cases where the stream from the response is not closed, the connections don't get released from the connection pool and in turn results in an indefinite wait time.
75+
76+
## Configuration for Apache Connector
77+
78+
### Configure the Connection Pool
79+
80+
The ApacheConfigurator configures a connection pool by default. However, the connnection pool can be configured
81+
or disabled. Configure the connection pool as follows:
82+
83+
final ApacheConnectorProperties apacheConnectorProperties =
84+
ApacheConnectorProperties.builder()
85+
//.connectionManager(connectionManager) to provide an instance of connectionManager
86+
.connectionPooling(true) // to enable/disable connection pooling
87+
.connectionPoolConfig(
88+
ApacheConnectionPoolConfig.builder()
89+
.defaultMaxConnectionsPerRoute(50)
90+
.totalOpenConnections(100).build()) // to set the connection pool configuration
91+
.build();
92+
final ApacheConfigurator configurator = new ApacheConfigurator.NonBuffering(apacheConnectorProperties);
93+
94+
Old way to configure and still works:
95+
96+
ApacheConnectionPoolConfig poolConfig = ApacheConnectionPoolConfig.builder()
97+
.defaultMaxConnectionsPerRoute(5)
98+
.totalOpenConnections(20)
99+
.ttl(2, TimeUnit.SECONDS)
100+
.build();
101+
ApacheConnectionPoolingClientConfigDecorator poolDecorator =
102+
new ApacheConnectionPoolingClientConfigDecorator(poolConfig);
103+
ApacheConfigurator configurator =
104+
new ApacheConfigurator(Collections.singletonList(poolDecorator));
105+
106+
IdentityClient identityClient = IdentityClient.builder()
107+
.clientConfigurator(configurator)
108+
.build(authenticationDetailsProvider);
109+
110+
Note : If the connection pooling is disabled, then the thread-safe `BasicHttpClientConnectionManager` is used for the Apache HttpClient.
111+
A connection manager for a single connection. This connection manager maintains only one active connection. Even
112+
though this class is fully thread-safe it ought to be used by one execution thread only, as only one thread a
113+
time can lease the connection at a time. This connection manager implementation should be used inside an EJB container.
114+
115+
Alternatively,
116+
117+
Documentation explaining the configuration concepts can be found [here](https://hc.apache.org/httpcomponents-client-ga/tutorial/html/connmgmt.html).
118+
119+
### Configure the HTTP Proxy
120+
121+
This add-on supports configuring a client to use a HTTP or HTTPS proxy. It is configured configured on a per-client basis, meaning that a proxy must be configured for each new client instance.
122+
123+
Configure an HTTP or HTTPS proxy as follows:
124+
125+
#### Authenticated Proxy
126+
127+
ApacheProxyConfig proxyConfig = ApacheProxyConfig.builder()
128+
.uri("http://proxy.domain.com:8000")
129+
.username("username")
130+
.password("password")
131+
.build();
132+
ClientConfigDecorator proxyConfigDecorator =
133+
new ApacheProxyConfigDecorator(proxyConfig);
134+
ClientConfigurator configurator =
135+
new ApacheConfigurator(Collections.singletonList(proxyConfigDecorator));
136+
137+
IdentityClient identityClient = IdentityClient.builder()
138+
.clientConfigurator(configurator)
139+
.build(authenticationDetailsProvider);
140+
141+
#### Unauthenticated Proxy
142+
143+
ApacheProxyConfig proxyConfig = ApacheProxyConfig.builder()
144+
.uri("https://proxy.domain.com:443")
145+
.build();
146+
ClientConfigDecorator proxyConfigDecorator =
147+
new ApacheProxyConfigDecorator(proxyConfig);
148+
ClientConfigurator configurator =
149+
new ApacheConfigurator(Collections.singletonList(proxyConfigDecorator));
150+
151+
IdentityClient identityClient = IdentityClient.builder()
152+
.clientConfigurator(configurator)
153+
.build(authenticationDetailsProvider);
154+
155+
#### Example
156+
An example of configuring a proxy can be found [here](https://github.com/oracle/oci-java-sdk/tree/master/bmc-examples/src/main/java/HttpProxyExample.java).
157+
158+
### Configure the SSLContext and HostNameVerifier
159+
160+
final ApacheConnectorProperties apacheConnectorProperties =
161+
ApacheConnectorProperties.builder()
162+
.sslContext(SSLContext.getDefault())
163+
.hostnameVerifier(NoopHostnameVerifier.INSTANCE)
164+
.build();
165+
final ApacheConfigurator configurator = new ApacheConfigurator.NonBuffering(apacheConnectorProperties);
166+
ObjectStorage client = ObjectStorageClient.builder()
167+
.clientConfigurator(configurator)
168+
.build(authenticationDetailsProvider);
169+
170+
## Known Issues
171+
172+
### Program hangs for an indefinite time
173+
174+
`ApacheConfigurator` by default configures a connection pool with `defaultMaxConnectionsPerRoute` and
175+
`maximumOpenConnections`. Please make sure to close all `InputStreams` obtained from the response object by
176+
calling close on the stream object if doing partial read. If the stream is read completely, then the SDK will try to
177+
auto-close the stream to release the connection from the connection pool.
178+
To manually close the stream in case of partial read of stream. Please call close on the stream.
179+
For example - `GetObjectReponse.getInputStream().close()` or
180+
use try-with-resources. Otherwise, a partial read without closing will lead to the connection not being released from
181+
the pool and results in hanging for an indefinite time.
182+
183+
### Performance issues and switching between connection closing strategies with the Apache Connector
184+
185+
The Java SDK supports the Apache Connector as the default. The Apache Connector supports the use of two connection closing strategies - `ApacheConnectionClosingStrategy.GracefulClosingStrategy` and `ApacheConnectionClosingStrategy.ImmediateClosingStrategy`.
186+
When using `ApacheConnectionClosingStrategy.GracefulClosingStrategy`, streams returned from response are read till the end of the stream when closing the stream. This can introduce additional time when closing the stream with partial read, depending on how large the remaining stream is.
187+
Use `ApacheConnectionClosingStrategy.ImmediateClosingStrategy` for large files with partial reads instead for faster close. One of the disadvantages of using
188+
`ApacheConnectionClosingStrategy.ImmediateClosingStrategy` on the other hand takes longer when using partial read for smaller stream size (< 1MB). Please consider your use-case and change accordingly.
189+
190+
Note : If both the above Apache Connection closing strategies do not give you optimal results for your use-cases, please consider switching back to Jersey Default `HttpUrlConnectorProvider` using the method stated in the above section.
191+
192+
An example can be found [here](http://https://github.com/oracle/oci-java-sdk/tree/master/bmc-examples/src/main/java/ApacheConnectorPropertiesExample.java "here")
193+
194+
## More info
195+
More examples related to customizing Apache Connector can be found [here](http://https://github.com/oracle/oci-java-sdk/tree/master/bmc-examples/src/main/java/ApacheConnectorPropertiesExample.java "here")
196+
197+
## License
198+
Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
199+
This software is dual-licensed to you under the Universal Permissive License (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl
200+
or Apache License 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose either license.
201+
202+
See [LICENSE](../../LICENSE.txt) for more details.

‎CHANGELOG.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,22 @@ All notable changes to this project will be documented in this file.
33

44
The format is based on [Keep a Changelog](http://keepachangelog.com/).
55

6+
## 2.0.0 - 2021-06-15
7+
### Added
8+
- Support for elastic storage on Exadata Infrastructure resources for Cloud at Customer in the Database service
9+
- Support for registration and management of target databases in the Data Safe service
10+
- Support for config on metadata in the Management Dashboard service
11+
- Support for a new work request operation type for node pool reconciliation events in the Container Engine for Kubernetes service
12+
- Support for migrating clusters with a public Kubernetes API endpoint which are not integrated with a customer's VCN to a VCN-native cluster in the Container Engine for Kubernetes service
13+
- Support for getting the spark version of applications, and filtering applications by spark version, in the Data Flow service
14+
15+
### Breaking Changes
16+
- Usage of Jersey's `ApacheConnectorProvider` by default to send requests to the service. For switching back to Jersey's default `HttpUrlConnectorProvider`, see "ApacheConnector-README"
17+
- Performance issues for APIs that return binary/stream response due to upgrade to Jersey's `ApacheConnectorProvider`. For more details, see "ApacheConnector-README"
18+
- Auto-close behavior for response streams on full-read for APIs that return binary/stream response. For more details, see "ApacheConnector-README"
19+
- Method `public java.util.Map getDefinedTags()` has been removed from the model `com.oracle.bmc.managementdashboard.model.ManagementDashboardExportDetails` in the Management Dashboard service
20+
- Method `public java.util.Map getFreeformTags()` has been removed from the model `com.oracle.bmc.managementdashboard.model.ManagementDashboardExportDetails` in the Management Dashboard service
21+
622
## 1.37.2 - 2021-06-08
723
### Added
824
- Support for Java Management service

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,25 @@ You can find information on any known issues with the SDK [here](https://docs.cl
5959

6060
**Direct link to this issue**: [Potential data corruption issue with OCI Java SDK on binary data upload with `RefreshableOnNotAuthenticatedProvider`](https://docs.cloud.oracle.com/en-us/iaas/Content/knownissues.htm#javaSDKStreamDataCorrupt)
6161

62+
### Program hangs for an indefinite time
63+
64+
If the request to the server hangs for an indefinite time and the program gets stuck, it could be
65+
because the connection is not released from the Apache connection
66+
pool. If you're calling APIs that return a binary/stream response,
67+
please make sure to close all the streams returned from the response to release the connections from the connection pool in case of partial reads. If reading the stream completely, the SDK will
68+
automatically try to close the stream to release the connection from the connection pool, to disable this feature of auto-closing streams on full read, please call `ResponseHelper.shouldAutoCloseResponseInputStream(false)`. 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 and in the cases where the stream from the response is not closed, the connections don't get released from the connection pool and in turn results in an indefinite wait time. This can be avoided either by closing the streams or switching back to the Jersey default connector, i.e. `HttpUrlConnector`. You can find more information about the same in the OCI Java SDK Troubleshooting section.
69+
70+
### Performance issues and switching between connection closing strategies with the Apache Connector
71+
72+
The Java SDK supports the Apache Connector as the default. The Apache Connector supports the use of two connection closing strategies - `ApacheConnectionClosingStrategy.GracefulClosingStrategy` and `ApacheConnectionClosingStrategy.ImmediateClosingStrategy`.
73+
When using `ApacheConnectionClosingStrategy.GracefulClosingStrategy`, streams returned from response are read till the end of the stream when closing the stream. This can introduce additional time when closing the stream with partial read, depending on how large the remaining stream is.
74+
Use `ApacheConnectionClosingStrategy.ImmediateClosingStrategy` for large files with partial reads instead for faster close. One of the disadvantages of using
75+
`ApacheConnectionClosingStrategy.ImmediateClosingStrategy` on the other hand takes longer when using partial read for smaller stream size (< 1MB). Please consider your use-case and change accordingly. For more info please look into : https://github.com/oracle/oci-java-sdk/blob/master/ApacheConnector-README.md.
76+
77+
Note : If both the above Apache Connection closing strategies do not give you optimal results for your use-cases, please consider switching back to Jersey Default `HttpUrlConnectorProvider`.
78+
For more info on Apache Connector, please look into ApacheConnector-README.
79+
80+
You can find information on any known issues with the SDK [here](https://docs.cloud.oracle.com/iaas/Content/knownissues.htm) and under the “Issues” tab of this GitHub repository.
6281

6382
## License
6483

0 commit comments

Comments
 (0)