Skip to content

Commit fada838

Browse files
yaroslav-kovalchykyaroslav-kovalchyk
committed
Merge pull request #151 from TanyaEf/master
Updated Readme.md (Configuration section)
2 parents 80dcd58 + ffd1f4e commit fada838

File tree

2 files changed

+107
-89
lines changed

2 files changed

+107
-89
lines changed

‎README.md‎

Lines changed: 106 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ Table of Contents
1111
* [Creation of manual configuration](#creation-of-manual-configuration).
1212
* [HTTPS configuration](#https-configuration).
1313
* [X-HTTP-Method override](#x-http-method-override).
14+
* [Switching of authentication type](#switching-authentication-type).
15+
* [Exception handling](#exception-handling).
16+
* [Logging](#logging).
17+
* [Switching between JSON and XML](#switching-between-json-and-xml).
1418
* [Client instantiation](#client-instantiation).
1519
3. [Authentication](#authentication).
1620
* [Anonymous session](#anonymous-session).
@@ -111,14 +115,11 @@ Table of Contents
111115
13. [Query executor service](#queryexecutor-service).
112116
14. [REST Server Information](#rest-server-information).
113117
15. [Bundles service](#bundles-service).
114-
16. [Exception handling](#exception-handling).
115-
17. [Asynchronous API](#asynchronous-api).
116-
18. [Getting serialized content from response](#getting-serialized-content-from-response).
117-
19. [Switching between JSON and XML](#switching-between-json-and-xml).
118-
20. [Logging](#logging).
119-
21. [Possible issues](#possible-issues).
120-
22. [Maven dependency to add jasperserver-rest-client to your app](#maven-dependency-to-add-jasperserver-rest-client-to-your-app).
121-
23. [License](#license).
118+
16. [Asynchronous API](#asynchronous-api).
119+
17. [Getting serialized content from response](#getting-serialized-content-from-response).
120+
18. [Possible issues](#possible-issues).
121+
19. [Maven dependency to add jasperserver-rest-client to your app](#maven-dependency-to-add-jasperserver-rest-client-to-your-app).
122+
20. [License](#license).
122123

123124
Introduction
124125
-------------
@@ -131,40 +132,43 @@ Configuration
131132
-------------
132133
To start working with the library you should firstly configure one ore more instances of `JasperserverRestClient`.
133134
To do this you should create instance of `RestClientConfiguration`. It can be done in two ways:
135+
- loading configuration from file;
136+
- creation of manual configuration in java code.
137+
134138
####Loading configuration from file:
135139
```java
136-
RestClientConfiguration configuration = RestClientConfiguration.loadConfiguration("url.properties");
140+
RestClientConfiguration configuration = RestClientConfiguration.loadConfiguration("configuration.properties");
137141
```
138142
Here is example of `configuration.properties` file:
139143
```java
140-
url=http://localhost:4444/jasperserver-pro
141-
connectionTimeout=100
144+
// required content
145+
url=http://localhost:8080/jasperserver-pro
146+
// optional content
147+
connectionTimeout=20
142148
readTimeout=20
143149
jasperserverVersion=v6_0_0
144-
authenticationType=REST
150+
authenticationType=SPRING
145151
logHttp=true
146-
logHttpEntity=false
152+
logHttpEntity=true
147153
restrictedHttpMethods=false
154+
handleErrors=true
148155
contentMimeType=JSON
149156
acceptMimeType=JSON
150157
```
151158
File must contain at least URL which is entry point to your server's REST services and it is needed to URL corresponds to this pattern `{protocol}://{host}:{port}/{contextPath}`.
159+
Please notice, configuration settings may be changed after loading manually in java code.
152160
####Creation of manual configuration
153161
To configure `JasperserverRestClient` manually, use the constructor of `RestClientConfiguration` and properties:
154162
```java
155163
RestClientConfiguration configuration = new RestClientConfiguration("http://localhost:8080/jasperserver");
156-
configuration.setAcceptMimeType(MimeType.JSON);
157-
configuration.setContentMimeType(MimeType.JSON);
158-
configuration.setJrsVersion(JRSVersion.v6_0_0);
159-
configuration.setLogHttp(true);
160-
configuration.setLogHttpEntity(true);
164+
configuration.setAcceptMimeType(MimeType.JSON).setContentMimeType(MimeType.JSON).setJrsVersion(JRSVersion.v6_0_0).setLogHttp(true);
161165
```
162166
####HTTPS configuration
163-
<strong>To use HTTPS you need:</strong>
164-
1. Configure your server to support HTTPS
165-
2. Download [InstallCert](http://miteff.com/files/InstallCert-bin.zip) util and follow [InstallCert-Guide](http://www.mkyong.com/webservices/jax-ws/suncertpathbuilderexception-unable-to-find-valid-certification-path-to-requested-target/) instructions.
166-
3. Set HTTPS as your protocol in server URL, e.g. `https://localhost:8443/jasperserver`
167-
4. Configure trusted certificates if needed
167+
**To use HTTPS you need:**
168+
1. Configure your server to support HTTPS
169+
2. Download [InstallCert](http://miteff.com/files/InstallCert-bin.zip) util and follow [InstallCert-Guide](http://www.mkyong.com/webservices/jax-ws/suncertpathbuilderexception-unable-to-find-valid-certification-path-to-requested-target/) instructions.
170+
3. Set HTTPS as your protocol in server URL, e.g. `https://localhost:8443/jasperserver`
171+
4. Configure trusted certificates if needed
168172

169173
```java
170174
RestClientConfiguration configuration = new RestClientConfiguration("https://localhost:8443/jasperserver");
@@ -176,11 +180,88 @@ configuration.setTrustManagers(trustManagers);
176180
####X-HTTP-Method override
177181
To avoid situation, when your proxies or web services do not support arbitrary HTTP methods or newer HTTP methods, you can use “restricted mode”. In this mode `JaperserverRestClient` sends requests through POST method and set the `X-HTTP-Method-Override` header with value of intended HTTP method. To use this mode you should set flag `RestrictedHttpMethods`:
178182
```java
179-
session.getStorage().getConfiguration().setRestrictedHttpMethods(true);
183+
configuration.setRestrictedHttpMethods(true);
180184
```
185+
Or in configuration file:
186+
```java
187+
restrictedHttpMethods=false
188+
````
181189
If you do not use the "restricted mode", POST or GET methods and server returns the response with 411 error code, `JaperserverRestClient` resend this request through POST method with the X-HTTP-Method-Override header automatically.
190+
####Switching authentication type
191+
`JasperserverRestClient` supports two authentication types: SPRING and BASIC.
192+
`SPRING` type of authentication means that your credentials are sent as a form to `/j_security_check directly/` uri. Using these types you obtain JSESSIONID cookie of authenticated session after sending credentials.
193+
In the `BASIC` mode `JasperserverRestClient` uses basic authentication (sends encrypted credentials with each request).
194+
Client uses `SPRING` authentication by default but you can specify authentication type in RestClientConfiguration instance:
195+
```java
196+
configuration.setAuthenticationType(AuthenticationType.SPRING);
197+
```
198+
Or set authentication type in configuration file:
199+
```java
200+
authenticationType=SPRING
201+
or
202+
authenticationType=BASIC
203+
```
204+
Please notice, the basic authentication is not stateless and it is valid till method logout() is called or the application is restarted and you can not use this authentication type for Report Service, because all operations must be executed in the same session (for details, read section [Report services](https://github.com/Jaspersoft/jrs-rest-java-client/blob/master/README.md#report-services)).
205+
####Exception handling
206+
You can choose strategy of errors that are specified by status code of server response:
207+
1. handling of errors directly. This mode is allowed by default.
208+
2. getting operation result in any case with null entity and handling error after calling `getEntity()` method:
209+
```java
210+
OperationResult<InputStream> result = session
211+
.thumbnailsService()
212+
.thumbnail()
213+
.report("/")
214+
.get(); // response status is 406, but exception won't be thrown
215+
result.getEntity(); // the error will be handled and an exception will be thrown
216+
```
217+
To apply the second strategy set `handleErrors` property of `RestCleintConfiguration` to `false`:
218+
```java
219+
configuration.setHandleErrors(false);
220+
```
221+
or specify this property in configuration file:
222+
```java
223+
handleErrors=false
224+
```
225+
You can customize exception handling for each endpoint. To do this you need to pass `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.ErrorHandler` implementation to `JerseyRequestBuilder.buildRequest()` factory method.
226+
227+
JRS REST client exception handling system is based on `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.ErrorHandler` interface. Its `void handleError(Response response)` method is responsible for all error handling logic. You can use existed handlers, define your own handlers or extend existed handlers.
228+
229+
1. Existed handlers:
230+
* `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.DefaultExceptionHandler` - this implementation is suitable for most of the JRS errors, but sometimes you can meet some not standart errors and here such implementations as `com.jaspersoft.jasperserver.jaxrs.client.apiadapters.jobs.JobValidationErrorHandler`, `com.jaspersoft.jasperserver.jaxrs.client.apiadapters.reporting.RunReportErrorHandler`, etc. take responsibility.
231+
2. You can create your own handler by implementing `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.ErrorHandler`.
232+
3. You can extend `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.DefaultExceptionHandler` or any other handler and override its methods `void handleBodyError(Response response)` and/or `void handleStatusCodeError(Response response, String overridingMessage)`.
233+
234+
####Logging
235+
It is possible to log outgoing requests and incoming responses using `logHttp` property of `RestCleintConfiguration`:
236+
```java
237+
config.setLogHttp(true);
238+
```
239+
Also, you are able to log entities using `logHttpEntity` option:
240+
```java
241+
config.setLogHttpEntity(true).
242+
```
243+
In configuration file:
244+
```java
245+
logHttp=true
246+
logHttpEntity=true
247+
```
248+
####Switching between JSON and XML
249+
You can configure a client to make request either with JSON or XML content.
250+
```java
251+
RestClientConfiguration configuration = new RestClientConfiguration("http://localhost:4444/jasperserver");
252+
configuration.setContentMimeType(MimeType.XML);
253+
configuration.setAcceptMimeType(MimeType.XML);
254+
```
255+
Or in `configuration.properties`:
256+
```
257+
contentMimeType=JSON
258+
acceptMimeType=JSON
259+
or
260+
contentMimeType=XML
261+
acceptMimeType=XML
262+
```
182263
####Client instantiation:
183-
Here everything is easy, you need just to pass `configuration` to `JasperserverRestClient` constructor.
264+
After configuration you need just to pass `configuration` instance to `JasperserverRestClient` constructor.
184265
```java
185266
JasperserverRestClient client = new JasperserverRestClient(configuration);
186267
```
@@ -193,15 +274,6 @@ Session session = client.authenticate("jasperadmin", "jasperadmin");
193274
//authentication with multitenancy enabled
194275
Session session = client.authenticate("jasperadmin|organization_1", "jasperadmin");
195276
```
196-
`JasperserverRestClient` supports two authentication types: SPRING and BASIC.
197-
`SPRING` type of authentication means that your credentials are sent as a form to `/j_security_check directly/` uri. Using these types you obtain JSESSIONID cookie of authenticated session after sending credentials.
198-
In the `BASIC` mode `JasperserverRestClient` uses basic authentication (sends encrypted credentials with each request).
199-
Client uses `SPRING` authentication by default but you can specify authentication type in RestClientConfiguration instance:
200-
```java
201-
config.setAuthenticationType(AuthenticationType.SPRING);
202-
```
203-
Or set authentication type in configuration file (for details, read section [Configuration](https://github.com/Jaspersoft/jrs-rest-java-client/blob/master/README.md#configuration)).
204-
Please notice, the basic authentication is not stateless and it is valid till method logout() is called or the application is restarted and you can not use this authentication type for Report Service, because all operations must be executed in the same session (for details, read section [Report services](https://github.com/Jaspersoft/jrs-rest-java-client/blob/master/README.md#report-services)).
205277
###Anonymous session
206278
For some Jasperserver services authentication is not required (for example, settings service, bundles service or server info service), so you can use anonymous session:
207279
```java
@@ -1727,32 +1799,6 @@ final Map<String, String> bundle = session
17271799
.bundle("jasperserver_messages")
17281800
.getEntity();
17291801
```
1730-
###Exception handling
1731-
You can choose strategy of errors that are specified by status code of server response:
1732-
1. handling of errors directly. This is allied by default.
1733-
2. getting operation result in any case with null entity and handling error after calling `getEntity()` method:
1734-
```java
1735-
OperationResult<InputStream> result = session
1736-
.thumbnailsService()
1737-
.thumbnail()
1738-
.report("/")
1739-
.get(); // response status is 406, but exception won't be thrown
1740-
result.getEntity(); // the error will be handled and an exception will be thrown
1741-
```
1742-
To apply the second strategy set `handleErrors` property of `RestCleintConfiguration` to `false`:
1743-
```java
1744-
configuration.setHandleErrors(false);
1745-
```
1746-
or specify this property in configuration file (for details, read section [Configuration](https://github.com/Jaspersoft/jrs-rest-java-client/blob/master/README.md#configuration)).
1747-
1748-
You can customize exception handling for each endpoint. To do this you need to pass `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.ErrorHandler` implementation to `JerseyRequestBuilder.buildRequest()` factory method.
1749-
1750-
JRS REST client exception handling system is based on `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.ErrorHandler` interface. Its `void handleError(Response response)` method is responsible for all error handling logic. You can use existed handlers, define your own handlers or extend existed handlers.
1751-
1752-
1. Existed handlers:
1753-
* `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.DefaultExceptionHandler` - this implementation is suitable for most of the JRS errors, but sometimes you can meet some not standart errors and here such implementations as `com.jaspersoft.jasperserver.jaxrs.client.apiadapters.jobs.JobValidationErrorHandler`, `com.jaspersoft.jasperserver.jaxrs.client.apiadapters.reporting.RunReportErrorHandler`, etc. take responsibility.
1754-
2. You can create your own handler by implementing `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.ErrorHandler`.
1755-
3. You can extend `com.jaspersoft.jasperserver.jaxrs.client.core.exceptions.handling.DefaultExceptionHandler` or any other handler and override its methods `void handleBodyError(Response response)` and/or `void handleStatusCodeError(Response response, String overridingMessage)`.
17561802
17571803
###Asynchronous API
17581804
Each operation which requests server has its asynchronous brother which has same name with `async` prefix, e. g. `get() -> asyncGet()`. Each of these operations take a `com.jaspersoft.jasperserver.jaxrs.client.core.Callback` implementation with `execute()` method implemented. `execute()` takes an `OperationResult` instance as a parameter. The `execute` method is called when the response from server came.
@@ -1780,35 +1826,6 @@ OperationResult<UsersListWrapper> result = ...
17801826
result.getSerializedContent();
17811827
```
17821828
1783-
###Switching between JSON and XML
1784-
You can configure a client to make request either with JSON or XML content.
1785-
```java
1786-
RestClientConfiguration configuration = new RestClientConfiguration("http://localhost:4444/jasperserver");
1787-
configuration.setContentMimeType(MimeType.XML);
1788-
configuration.setAcceptMimeType(MimeType.XML);
1789-
```
1790-
or you can externilize configuration
1791-
```
1792-
url=http://localhost:4444/jasperserver/
1793-
contentMimeType=JSON
1794-
acceptMimeType=JSON
1795-
#contentMimeType=XML
1796-
#acceptMimeType=XML
1797-
```
1798-
```java
1799-
RestClientConfiguration configuration = RestClientConfiguration.loadConfiguration("jrs-client-config.properties");
1800-
```
1801-
1802-
###Logging
1803-
It is possible to log outgoing requests and incoming responses using `logHttp` property of `RestCleintConfiguration`:
1804-
```java
1805-
config.setLogHttp(true);
1806-
```
1807-
Also, you are able to log entities using `logHttpEntity` option:
1808-
```java
1809-
config.setLogHttpEntity(true).
1810-
```
1811-
18121829
###Possible issues
18131830
1. <strong>Deploying jrs-rest-client within web app to any Appplication Server, e.g. JBoss, Glassfish, WebSphere etc.</strong>
18141831
jrs-rest-client uses the implementation of JAX-RS API of version 2.0 and if your application server does not support this version you will get an error. To solve this problem you need to add to your application a deployment configuration specific for your AS where you need to exclude modules with old JAX-RS API version. Example of such descriptor for JBoss AS you can find below:

‎src/main/resources/config.properties‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@ authenticationType=SPRING
77
logHttp=true
88
logHttpEntity=true
99
restrictedHttpMethods=false
10+
handleErrors=true
1011
contentMimeType=JSON
1112
acceptMimeType=JSON

0 commit comments

Comments
 (0)