Skip to content

Commit a21dca0

Browse files
mmallis87mmallis87
authored
Merge pull request #107 from docusign/Java-Readme-Update
Java readme update
2 parents 1fd2056 + 7277828 commit a21dca0

File tree

1 file changed

+57
-269
lines changed

1 file changed

+57
-269
lines changed

‎README.md‎

Lines changed: 57 additions & 269 deletions
Original file line numberDiff line numberDiff line change
@@ -1,304 +1,92 @@
1-
# The Official DocuSign Java Client
1+
# The Official DocuSign Java Client
22

33
[![Build status][travis-image]][travis-url]
44
[![Maven Central status][maven-image]][maven-url]
55

6-
You can sign up for a free [developer sandbox](https://go.docusign.com/sandbox/productshot/?elqCampaignId=16533).
6+
# The Official DocuSign Java Client
77

8-
Requirements
9-
============
8+
## Requirements
109

11-
Java 1.7 or later.
10+
- Java 1.7+
11+
- Free [Developer Sandbox](https://go.docusign.com/sandbox/productshot/?elqCampaignId=16531)
1212

13-
Installation
14-
============
13+
## Compatibility
1514

16-
### Maven users
15+
- Java 1.7+
1716

18-
Add this dependency to your project's POM:
17+
## Note
1918

20-
```xml
21-
<dependency>
22-
<groupId>com.docusign</groupId>
23-
<artifactId>docusign-esign-java</artifactId>
24-
<version>2.9.0</version>
25-
</dependency>
26-
```
19+
This open-source SDK is provided for cases where you would like to make additional changes that the SDK does not provide out-of-the-box. If you simply want to use the SDK with any of the examples shown in the [Developer Center](https://developers.docusign.com/esign-rest-api/code-examples), follow the installation instructions below.
20+
21+
## Installation
2722

28-
### Gradle users
23+
Note: DocuSign uses **Eclipse** with **Maven** for testing purposes.
2924

30-
Add this dependency to your project's build file:
25+
### Maven:
3126

32-
```groovy
33-
compile "com.docusign:docusign-esign-java:2.9.0"
27+
1. In Eclipse, create a new project by selecting **File** -> **New** -> **Project**.
28+
2. In the **New Project Wizard** , expand **Maven** , then select **Maven Project.**
29+
3. Leave **Create a simple project** unchecked.
30+
4. Select **Next** , then provide a unique **Group** and **Artifact Id**.
31+
5. In the directory where you've saved your project, open the _pom.xml_ file.
32+
6. In the _pom.xml_ file, locate the **dependencies** node.
33+
7. Add:
34+
35+
```
36+
<dependency>
37+
<groupId>com.docusign</groupId>
38+
<artifactId>docusign-esign-java</artifactId>
39+
<version>2.9.0</version>
40+
</dependency>
3441
```
3542

36-
#### Dependencies
43+
8. If your project is still open, restart **Eclipse**.
3744

38-
This client has the following external dependencies:
45+
## Dependencies
3946

40-
* io.swagger:swagger-annotations:jar:1.5.8
41-
* com.sun.jersey:jersey-client:jar:1.19.1
42-
* com.sun.jersey.contribs:jersey-multipart:jar:1.19.1
43-
* com.fasterxml.jackson.core:jackson-core:jar:2.9.5
44-
* com.fasterxml.jackson.core:jackson-annotations:jar:2.9.5
45-
* com.fasterxml.jackson.core:jackson-databind:jar:2.9.5
46-
* com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider:jar:2.9.5
47-
* com.fasterxml.jackson.datatype:jackson-datatype-joda:jar:2.1.5
48-
* joda-time:joda-time:jar:2.9.3
49-
* com.brsanthu:migbase64:jar:2.2
50-
* org.apache.oltu.oauth2:org.apache.oltu.oauth2.client:1.0.2
51-
* junit:junit:jar:4.12
47+
This client has the following external dependencies:
5248

53-
#### Note for Android Developers
49+
- swagger:swagger-annotations:jar:1.5.8
50+
- sun.jersey:jersey-client:jar:1.19.1
51+
- sun.jersey.contribs:jersey-multipart:jar:1.19.1
52+
- fasterxml.jackson.core:jackson-core:jar:2.9.5
53+
- fasterxml.jackson.core:jackson-annotations:jar:2.9.5
54+
- fasterxml.jackson.core:jackson-databind:jar:2.9.5
55+
- fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider:jar:2.9.5
56+
- fasterxml.jackson.datatype:jackson-datatype-joda:jar:2.1.5
57+
- joda-time:joda-time:jar:2.9.3
58+
- brsanthu:migbase64:jar:2.2
59+
- apache.oltu.oauth2:org.apache.oltu.oauth2.client:1.0.2
60+
- junit:junit:jar:4.12
5461

55-
If you encounter build errors due to duplicate definitions, include the following in your build.gradle module:
62+
## Code Examples
5663

57-
```
58-
android {
59-
packagingOptions {
60-
pickFirst 'META-INF/services/javax.ws.rs.ext.MessageBodyReader’
61-
pickFirst 'META-INF/services/javax.ws.rs.ext.MessageBodyWriter’
62-
pickFirst 'META-INF/services/com.sun.jersey.spi.inject.InjectableProvider’
63-
pickFirst 'META-INF/jersey-module-version' pickFirst 'META-INF/NOTICE’
64-
pickFirst 'META-INF/LICENSE’
65-
pickFirst 'META-INF/services/com.fasterxml.jackson.databind.Module’
66-
pickFirst 'META-INF/services/com.fasterxml.jackson.core.ObjectCodec’
67-
pickFirst 'META-INF/services/com.fasterxml.jackson.core.JsonFactory’
68-
}
69-
}
70-
```
64+
### Launchers
7165

72-
### Package Managers
73-
74-
This client is available through the following Java package managers:
75-
76-
- [Nexus Repository Manager](https://oss.sonatype.org/#nexus-search;quick~docusign-esign-java) (oss.sonatype.org). You can search for com.docusign or docusign-esign-java. The current version is 2.9.0.
77-
- [JFrog Bintray](https://bintray.com/dsdevcenter/maven/docusign-esign-java) (bintray.com). You can search for com.docusign or docusign-esign-java. The current version is 2.9.0.
78-
79-
80-
Usage
81-
=====
82-
83-
To send a signature request from a Template using OAuth Authorization Code Grant:
84-
85-
```java
86-
import com.docusign.esign.api.*;
87-
import com.docusign.esign.client.*;
88-
import com.docusign.esign.model.*;
89-
import com.docusign.esign.client.auth.OAuth;
90-
import com.docusign.esign.client.auth.OAuth.UserInfo;
91-
import java.awt.Desktop;
92-
93-
import java.io.IOException;
94-
95-
public class DocuSignExample {
96-
public static void main(String[] args) {
97-
String RedirectURI = "[REDIRECT_URI]";
98-
String ClientSecret = "[CLIENT_SECRET]";
99-
String IntegratorKey = "[INTEGRATOR_KEY]";
100-
String BaseUrl = "https://demo.docusign.net/restapi";
101-
102-
ApiClient apiClient = new ApiClient(BaseUrl);
103-
try
104-
{
105-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
106-
// STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL
107-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
108-
109-
String randomState = "[random_string]";
110-
java.util.List<String> scopes = new java.util.ArrayList<String>();
111-
scopes.add(OAuth.Scope_SIGNATURE);
112-
// get DocuSign OAuth authorization url
113-
URI oauthLoginUrl = apiClient.getAuthorizationUri(IntegratorKey, scopes, RedirectURI, OAuth.CODE, randomState);
114-
// open DocuSign OAuth login in the browser
115-
Desktop.getDesktop().browse(oauthLoginUrl);
116-
// IMPORTANT: after the login, DocuSign will send back a fresh
117-
// authorization code as a query param of the redirect URI.
118-
// You should set up a route that handles the redirect call to get
119-
// that code and pass it to token endpoint as shown in the next
120-
// lines:
121-
/*String code = "[once_you_get_the_oauth_code_put_it_here]";
122-
OAuth.OAuthToken oAuthToken = apiClient.generateAccessToken(IntegratorKey, ClientSecret, code);
123-
124-
System.out.println("OAuthToken: " + oAuthToken);
125-
126-
// now that the API client has an OAuth token, let's use it in all
127-
// DocuSign APIs
128-
UserInfo userInfo = apiClient.getUserInfo(oAuthToken.getAccessToken());
129-
130-
System.out.println("UserInfo: " + userInfo);
131-
// parse first account's baseUrl
132-
// below code required for production, no effect in demo (same
133-
// domain)
134-
apiClient.setBasePath(userInfo.getAccounts().get(0).getBaseUri() + "/restapi");
135-
Configuration.setDefaultApiClient(apiClient);
136-
String accountId = userInfo.getAccounts().get(0).getAccountId();*/
137-
138-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
139-
// *** STEP 2: CREATE ENVELOPE FROM TEMPLATE
140-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
141-
142-
// create a new envelope to manage the signature request
143-
EnvelopeDefinition envDef = new EnvelopeDefinition();
144-
envDef.setEmailSubject("DocuSign Java SDK - Sample Signature Request");
145-
146-
// assign template information including ID and role(s)
147-
envDef.setTemplateId("[TEMPLATE_ID]");
148-
149-
// create a template role with a valid templateId and roleName and assign signer info
150-
TemplateRole tRole = new TemplateRole();
151-
tRole.setRoleName("[ROLE_NAME]");
152-
tRole.setName("[SIGNER_NAME]");
153-
tRole.setEmail("[SIGNER_EMAIL]");
154-
155-
// create a list of template roles and add our newly created role
156-
java.util.List<TemplateRole> templateRolesList = new java.util.ArrayList<TemplateRole>();
157-
templateRolesList.add(tRole);
158-
159-
// assign template role(s) to the envelope
160-
envDef.setTemplateRoles(templateRolesList);
161-
162-
// send the envelope by setting |status| to "sent". To save as a draft set to "created"
163-
envDef.setStatus("sent");
164-
165-
// instantiate a new EnvelopesApi object
166-
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
167-
168-
// call the createEnvelope() API
169-
EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
170-
}
171-
catch (ApiException ex)
172-
{
173-
System.out.println("Exception: " + ex);
174-
}
175-
catch (Exception e)
176-
{
177-
System.out.println("Exception: " + e.getLocalizedMessage());
178-
}
179-
}
180-
}
181-
```
66+
DocuSign provides a sample application referred to as a [Launcher](https://github.com/docusign/eg-03-java-auth-code-grant). The Launcher contains a set of 14 common use cases and associated source files. These examples use DocuSign's [Authorization Code Grant](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-code-grant) flow.
18267

183-
To send a signature request from a Template using JWT Auth (for service integrations):
184-
185-
```java
186-
import com.docusign.esign.api.*;
187-
import com.docusign.esign.client.*;
188-
import com.docusign.esign.model.*;
189-
import com.docusign.esign.client.auth.OAuth;
190-
import com.docusign.esign.client.auth.OAuth.UserInfo;
191-
192-
import java.io.IOException;
193-
194-
public class DocuSignExample {
195-
public static void main(String[] args) {
196-
String OAuthBaseUrl = "account-d.docusign.com";
197-
String BaseUrl = "https://demo.docusign.net/restapi";
198-
String RedirectURI = "[OAUTH_REDIRECT_URI]";
199-
String IntegratorKey = "[INTEGRATOR_KEY]";
200-
String UserId = "[USER_ID_TO_SEND_ON_BEHALF]";
201-
String publicKeyFilename = "[PATH_TO_RSA265_PUBLIC_KEY]";
202-
String privateKeyFilename = "[PATH_TO_RSA265_PRIVATE_KEY]";
203-
204-
ApiClient apiClient = new ApiClient(BaseUrl);
205-
206-
try {
207-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
208-
// STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL
209-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
210-
211-
// IMPORTANT NOTE:
212-
// the first time you ask for a JWT access token, you should grant access by making the following call
213-
// get DocuSign OAuth authorization url:
214-
//String oauthLoginUrl = apiClient.getJWTUri(IntegratorKey, RedirectURI, OAuthBaseUrl);
215-
// open DocuSign OAuth authorization url in the browser, login and grant access
216-
//Desktop.getDesktop().browse(URI.create(oauthLoginUrl));
217-
// END OF NOTE
218-
219-
apiClient.configureJWTAuthorizationFlow(publicKeyFilename, privateKeyFilename, OAuthBaseUrl, IntegratorKey, UserId, 3600); // request for a fresh JWT token valid for 1 hour
220-
221-
// now that the API client has an OAuth token, let's use it in all
222-
// DocuSign APIs
223-
UserInfo userInfo = apiClient.getUserInfo(apiClient.getAccessToken());
224-
225-
System.out.println("UserInfo: " + userInfo);
226-
// parse first account's baseUrl
227-
// below code required for production, no effect in demo (same
228-
// domain)
229-
apiClient.setBasePath(userInfo.getAccounts().get(0).getBaseUri() + "/restapi");
230-
Configuration.setDefaultApiClient(apiClient);
231-
String accountId = userInfo.getAccounts().get(0).getAccountId();
232-
233-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
234-
// *** STEP 2: CREATE ENVELOPE FROM TEMPLATE
235-
/////////////////////////////////////////////////////////////////////////////////////////////////////////
236-
237-
// create a new envelope to manage the signature request
238-
EnvelopeDefinition envDef = new EnvelopeDefinition();
239-
envDef.setEmailSubject("DocuSign Java SDK - Sample Signature Request");
240-
241-
// assign template information including ID and role(s)
242-
envDef.setTemplateId("[TEMPLATE_ID]");
243-
244-
// create a template role with a valid templateId and roleName and assign signer info
245-
TemplateRole tRole = new TemplateRole();
246-
tRole.setRoleName("[ROLE_NAME]");
247-
tRole.setName("[SIGNER_NAME]");
248-
tRole.setEmail("[SIGNER_EMAIL]");
249-
250-
// create a list of template roles and add our newly created role
251-
java.util.List<TemplateRole> templateRolesList = new java.util.ArrayList<TemplateRole>();
252-
templateRolesList.add(tRole);
253-
254-
// assign template role(s) to the envelope
255-
envDef.setTemplateRoles(templateRolesList);
256-
257-
// send the envelope by setting |status| to "sent". To save as a draft set to "created"
258-
envDef.setStatus("sent");
259-
260-
// instantiate a new EnvelopesApi object
261-
EnvelopesApi envelopesApi = new EnvelopesApi();
262-
263-
// call the createEnvelope() API
264-
EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
265-
} catch (ApiException ex) {
266-
System.out.println("Exception: " + ex);
267-
} catch (Exception e) {
268-
System.out.println("Exception: " + e.getLocalizedMessage());
269-
}
270-
}
271-
}
272-
```
68+
### Proof-of-concept applications
27369

274-
See [SdkUnitTests.java](https://github.com/docusign/docusign-java-client/blob/master/src/test/java/SdkUnitTests.java) for more examples.
70+
If your goal is to create a proof-of-concept application, DocuSign provides a set of [Quick Start](https://github.com/docusign/qs-java) examples. The Quick Start examples are meant to be used with DocuSign's [OAuth Token Generator](https://developers.docusign.com/oauth-token-generator), which will allow you to generate tokens for the Demo/Sandbox environment only. These tokens last for eight hours and will enable you to build your proof-of-concept application without the need to fully implement an OAuth solution.
27571

276-
# Authentication
72+
## OAuth Implementations
27773

278-
## User Applications that use OAuth Authentication
279-
1. After obtaining a Bearer token, call the [OAuth: Userinfo method](https://docs.docusign.com/esign/guide/authentication/userinfo.html). Obtain the selected account's `base_uri` (server name) field.
280-
The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment.
281-
1. Combine the base_uri with "/restapi" to create the basePath. The base_uri will start with na1, na2, na3, eu1, or something else. Use the basePath for your subsequent API calls.
282-
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
283-
5. Create the `authentication_value` by combining the `token_type` and `access_token` fields you receive from either an [Authorization Code Grant](https://docs.docusign.com/esign/guide/authentication/oa2_auth_code.html) or [Implicit Grant](https://docs.docusign.com/esign/guide/authentication/oa2_implicit.html) OAuth flow.
284-
5. Set the authentication header by using `Configuration.Default.AddDefaultHeader('Authorization', authentication_value)`
74+
For details regarding which type of OAuth grant will work best for your DocuSign integration, see the [REST API Authentication Overview](https://developers.docusign.com/esign-rest-api/guides/authentication) guide located on the [DocuSign Developer Center](https://developers.docusign.com/esign-rest-api/guides/authentication).
28575

286-
Testing
287-
=======
76+
For security purposes, DocuSign recommends using the Authorization Code Grant flow.
28877

289-
You must have Maven installed. To run the tests:
78+
There are other use-case scenarios, such as **single page applications** (SPA) that use **Cross-Origin Resource Sharing** (CORS), or where there may not be a user to interact with your Service Account. For these use cases, DocuSign also supports [JWT](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-jsonwebtoken) and [Implicit](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-implicit) grants. For code examples, see the links below:
29079

291-
mvn test
80+
- [JWT (JSON Web Token)](https://github.com/docusign/eg-01-java-jwt)
81+
- Implicit Grant (coming soon)
29282

293-
Support
294-
=======
83+
## Support
29584

296-
Feel free to log issues against this client through GitHub. We also have an active developer community on Stack Overflow, search the [DocuSignAPI](http://stackoverflow.com/questions/tagged/docusignapi) tag.
85+
Log issues against this client through GitHub. We also have an [active developer community on Stack Overflow](http://stackoverflow.com/questions/tagged/docusignapi).
29786

298-
License
299-
=======
87+
## License
30088

301-
The DocuSign Java Client is licensed under the following [License](LICENSE).
89+
The DocuSign Java Client is licensed under the [MIT License](https://github.com/docusign/docusign-java-client/blob/master/LICENSE).
30290

30391

30492
[travis-image]: https://img.shields.io/travis/docusign/docusign-java-client.svg?style=flat

0 commit comments

Comments
 (0)