Skip to content

Commit c36e22d

Browse files
stern-shawnstern-shawn
authored
docs: consolidate (#739)
* docs: migrate custom http client example from docs * docs: consolidate docs information with README.md
1 parent 58b3f87 commit c36e22d

File tree

4 files changed

+402
-95
lines changed

4 files changed

+402
-95
lines changed

‎CONTRIBUTING.md

-6
Original file line numberDiff line numberDiff line change
@@ -75,10 +75,6 @@ you're working on.
7575
For large fixes, please build and test the documentation before submitting the
7676
PR to be sure you haven't accidentally introduced layout or formatting issues.
7777

78-
If you want to help improve the docs at
79-
[https://www.twilio.com/docs/libraries/java][docs-link], please contact
80-
[help@twilio.com](mailto:help@twilio.com).
81-
8278
## <a name="submit"></a> Submission Guidelines
8379

8480
### Submitting an Issue
@@ -162,7 +158,5 @@ you are working:
162158
* All features or bug fixes **must be tested** by one or more tests.
163159
* All classes and methods **must be documented**.
164160
165-
166-
[docs-link]: https://www.twilio.com/docs/libraries/java
167161
[issue-link]: https://github.com/twilio/twilio-java/issues/new
168162
[github]: https://github.com/twilio/twilio-java

‎README.md

+176-87
Original file line numberDiff line numberDiff line change
@@ -22,60 +22,200 @@ New accounts and subaccounts are now required to use TLS 1.2 when accessing the
2222

2323
This library supports the following Java implementations:
2424

25-
* OpenJDK 8
26-
* OpenJDK 11
27-
* OpenJDK 17
28-
* OracleJDK 8
29-
* OracleJDK 11
30-
* OracleJDK 17
25+
- OpenJDK 8
26+
- OpenJDK 11
27+
- OpenJDK 17
28+
- OracleJDK 8
29+
- OracleJDK 11
30+
- OracleJDK 17
3131

3232
For Java 7 support, use `twilio-java` major version `7.X.X`.
3333

3434
## Installation
3535

36-
twilio-java uses Maven. At present the jars *are* available from a public [maven](https://mvnrepository.com/artifact/com.twilio.sdk/twilio) repository.
36+
`twilio-java` uses Maven. At present the jars _are_ available from a public [maven](https://mvnrepository.com/artifact/com.twilio.sdk/twilio) repository.
3737

3838
Use the following dependency in your project to grab via Maven:
3939

40-
```
41-
<dependency>
42-
<groupId>com.twilio.sdk</groupId>
43-
<artifactId>twilio</artifactId>
44-
<version>9.X.X</version>
45-
<scope>compile</scope>
46-
</dependency>
40+
```xml
41+
<dependency>
42+
<groupId>com.twilio.sdk</groupId>
43+
<artifactId>twilio</artifactId>
44+
<version>9.X.X</version>
45+
<scope>compile</scope>
46+
</dependency>
4747
```
4848

4949
or Gradle:
50+
5051
```groovy
5152
implementation "com.twilio.sdk:twilio:9.X.X"
5253
```
5354

5455
If you want to compile it yourself, here's how:
5556

56-
$ git clone git@github.com:twilio/twilio-java
57-
$ cd twilio-java
58-
$ mvn install # Requires maven, download from https://maven.apache.org/download.html
57+
```shell
58+
git clone git@github.com:twilio/twilio-java
59+
cd twilio-java
60+
mvn install # Requires maven, download from https://maven.apache.org/download.html
61+
```
5962

6063
If you want to build your own .jar, execute the following from within the cloned directory:
6164

62-
$ mvn package
65+
```shell
66+
mvn package
67+
```
6368

6469
If you run into trouble with local tests, use:
6570

66-
$ mvn package -Dmaven.test.skip=true
71+
```shell
72+
mvn package -Dmaven.test.skip=true
73+
```
74+
75+
### Test your installation
76+
77+
Try sending yourself an SMS message, like this:
78+
79+
```java
80+
import com.twilio.Twilio;
81+
import com.twilio.rest.api.v2010.account.Message;
82+
import com.twilio.type.PhoneNumber;
83+
84+
public class Example {
85+
86+
// Find your Account Sid and Token at console.twilio.com
87+
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
88+
public static final String AUTH_TOKEN = "your_auth_token";
6789

68-
## Quickstart
90+
public static void main(String[] args) {
91+
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
92+
93+
Message message = Message
94+
.creator(
95+
new PhoneNumber("+15558675309"),
96+
new PhoneNumber("+15017250604"),
97+
"This is the ship that made the Kessel Run in fourteen parsecs?"
98+
)
99+
.create();
100+
101+
System.out.println(message.getSid());
102+
}
103+
}
104+
```
105+
106+
> **Warning**
107+
> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
108+
109+
## Usage
69110

70111
### Initialize the Client
71112

72113
```java
73-
// Find your Account SID and Auth Token at twilio.com/console
74-
// DANGER! This is insecure. See http://twil.io/secure
75-
String accountSid = "ACXXXXXX";
76-
String authToken = "XXXXXXXX";
114+
import com.twilio.Twilio;
115+
import com.twilio.exception.AuthenticationException;
77116

78-
Twilio.init(accountSid, authToken);
117+
public class Example {
118+
119+
private static final String ACCOUNT_SID =
120+
"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
121+
private static final String AUTH_TOKEN = "your_auth_token";
122+
123+
public static void main(String[] args) throws AuthenticationException {
124+
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
125+
}
126+
}
127+
```
128+
129+
### Environment Variables
130+
131+
`twilio-java` supports the credentials, region, and edge values stored in the following environment variables:
132+
133+
- `TWILIO_ACCOUNT_SID`
134+
- `TWILIO_AUTH_TOKEN`
135+
- `TWILIO_REGION`
136+
- `TWILIO_EDGE`
137+
138+
If using these variables, the above client initialization can be skipped.
139+
140+
### Make a Call
141+
142+
```java
143+
import com.twilio.Twilio;
144+
import com.twilio.rest.api.v2010.account.Call;
145+
import com.twilio.type.PhoneNumber;
146+
import java.net.URI;
147+
import java.net.URISyntaxException;
148+
149+
public class Example {
150+
151+
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
152+
public static final String AUTH_TOKEN = "your_auth_token";
153+
154+
public static void main(String[] args) throws URISyntaxException {
155+
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
156+
157+
Call call = Call
158+
.creator(
159+
new PhoneNumber("+14155551212"),
160+
new PhoneNumber("+15017250604"),
161+
new URI("http://demo.twilio.com/docs/voice.xml")
162+
)
163+
.create();
164+
165+
System.out.println(call.getSid());
166+
}
167+
}
168+
```
169+
170+
### Get an existing Call
171+
172+
```java
173+
import com.twilio.Twilio;
174+
import com.twilio.rest.api.v2010.account.Call;
175+
176+
public class Example {
177+
178+
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
179+
public static final String AUTH_TOKEN = "your_auth_token";
180+
181+
public static void main(String[] args) {
182+
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
183+
184+
Call call = Call.fetcher("CA42ed11f93dc08b952027ffbc406d0868").fetch();
185+
186+
System.out.println(call.getTo());
187+
}
188+
}
189+
```
190+
191+
### Iterate through records
192+
193+
The library automatically handles paging for you. With the `read` method, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`pageSize`). The library will then handle the task for you, fetching new pages under the hood as you iterate over the records.
194+
195+
For more information, view the [auto-generated library docs](https://www.twilio.com/docs/libraries/reference/twilio-java/).
196+
197+
#### Use the `read` method
198+
199+
```java
200+
import com.twilio.Twilio;
201+
import com.twilio.base.ResourceSet;
202+
import com.twilio.rest.api.v2010.account.Call;
203+
204+
public class Example {
205+
206+
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
207+
public static final String AUTH_TOKEN = "your_auth_token";
208+
209+
public static void main(String[] args) {
210+
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
211+
212+
ResourceSet<Call> calls = Call.reader().read();
213+
214+
for (Call call : calls) {
215+
System.out.println(call.getDirection());
216+
}
217+
}
218+
}
79219
```
80220

81221
### Specify Region and/or Edge
@@ -96,9 +236,9 @@ This library uses SLF4J for logging. Consult the [SFL4J documentation](http://sl
96236

97237
For example, if you are using `log4j`:
98238

99-
* Make sure you have `log4j-slf4j-impl`, `log4j-core` and `log4j-api` in your `pom.xml` file
100-
* Define the logging level for the Twilio HTTP client in your configuration. For example, in `src/main/resources/log4j2.xml`:
101-
239+
- Make sure you have `log4j-slf4j-impl`, `log4j-core` and `log4j-api` in your `pom.xml` file
240+
- Define the logging level for the Twilio HTTP client in your configuration. For example, in `src/main/resources/log4j2.xml`:
241+
102242
```xml
103243
<?xml version="1.0" encoding="UTF-8"?>
104244
<Configuration status="WARN">
@@ -119,43 +259,7 @@ For example, if you are using `log4j`:
119259
</Configuration>
120260
```
121261

122-
### Environment Variables
123-
124-
`twilio-java` supports the credentials, region, and edge values stored in the following environment variables:
125-
* `TWILIO_ACCOUNT_SID`
126-
* `TWILIO_AUTH_TOKEN`
127-
* `TWILIO_REGION`
128-
* `TWILIO_EDGE`
129-
130-
If using these variables, the above client initialization can be skipped.
131-
132-
### Send an SMS
133-
134-
```java
135-
Message message = Message.creator(
136-
new PhoneNumber("+15558881234"), // To number
137-
new PhoneNumber("+15559994321"), // From number
138-
"Hello world!" // SMS body
139-
).create();
140-
141-
System.out.println(message.getSid());
142-
```
143-
144-
### Make a Call
145-
146-
```java
147-
Call call = Call.creator(
148-
new PhoneNumber("+15558881234"), // To number
149-
new PhoneNumber("+15559994321"), // From number
150-
151-
// Read TwiML at this URL when a call connects (hold music)
152-
new URI("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
153-
).create();
154-
155-
System.out.println(call.getSid());
156-
```
157-
158-
### Handling Exceptions
262+
### Handle Exceptions
159263

160264
```java
161265
import com.twilio.exception.ApiException;
@@ -173,23 +277,7 @@ try {
173277
}
174278
```
175279

176-
For more descriptive exception types, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/java/usage-guide#exceptions).
177-
178-
### Using a Different Client
179-
180-
```java
181-
TwilioRestClient client = new TwilioRestClient.Builder(accountSid, authToken).build();
182-
183-
Message message = Message.creator(
184-
new PhoneNumber("+15558881234"), // To number
185-
new PhoneNumber("+15559994321"), // From number
186-
"Hello world!" // SMS body
187-
).create(client); // Pass the client here
188-
189-
System.out.println(message.getSid());
190-
```
191-
192-
### Using a Client With PKCV Authentication
280+
### Use a Client With PKCV Authentication
193281

194282
Additional documentation here: https://twilio.com/docs/iam/pkcv/quickstart
195283

@@ -201,7 +289,7 @@ TwilioRestClient client = new TwilioRestClient.Builder(signingKey.getSid(), sign
201289
.build();
202290
```
203291

204-
### Generating TwiML
292+
### Generate TwiML
205293

206294
To control phone calls, your application needs to output [TwiML][twiml].
207295

@@ -215,18 +303,19 @@ TwiML twiml = new VoiceResponse.Builder()
215303
```
216304

217305
That will output XML that looks like this:
218-
```
306+
307+
```xml
219308
<Response>
220309
<Say>Hello World!</Say>
221310
<Play loop="5">https://api.twilio.com/cowbell.mp3</Play>
222311
</Response>
223312
```
224313

225-
## Using a Custom HTTP Client
314+
### Use a custom HTTP Client
226315

227-
To use a custom HTTP client with this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/java/custom-http-clients-java).
316+
To use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md).
228317

229-
## Docker Image
318+
## Docker image
230319

231320
The `Dockerfile` present in this repository and its respective `twilio/twilio-java` Docker image are currently used by Twilio for testing purposes only.
232321

‎UPGRADE.md

-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ _`MAJOR` version bumps will have upgrade notes posted here._
1010

1111
Behind the scenes Java Helper is now auto-generated via OpenAPI with this release. This enables us to rapidly add new features and enhance consistency across versions and languages.
1212

13-
To learn more about the Java Helper Library, check out [our docs](https://www.twilio.com/docs/libraries/java).
14-
1513
[2020-09-28] 7.x.x to 8.x.x
1614
-----------------------------
1715

0 commit comments

Comments
 (0)