Learn about the Square Java SDK features.
import statement allows you to use types defined in a namespace without specifying the fully qualified namespace of that type. You can add the following
import statements to import all the types from the Square namespace:
To use the Square API, instantiate a
SquareClient object and initialize it with the appropriate environment and corresponding access token, as shown:
For testing, Square provides a Sandbox environment.
To access production resources, set the environment to
To set a custom environment, provide a
CustomUrland set the environment to
Each Square API request must be authenticated. Don't hardcode credentials (access tokens) in your code. The Quickstart exercise uses a configuration file in the project to store credentials. Your code can then read the credentials, as shown in the following code fragment:
The configuration file (
config.properties) looks like the following:
The Square Java SDK uses the
CompletableFuture framework for its asynchronous implementation. Each asynchronous API call returns a
CompletableFuture object, and you can orchestrate and combine them into a pipeline that returns a single result. For more information, see CompletableFuture.
The following example shows how to make an asynchronous call:
Note the following about this code:
thenAcceptmethod defines actions to take if the operation is successful.
exceptionallymethod defines actions to take if the operation returns an error.
joinmethod waits for the operation to complete and then returns control to the main program.
After you make the last async call in a program, use the Square client
shutdown method before the program exits.
Otherwise, the program stops responding for approximately 60 seconds until the async threads time out.
com.squareup.square.models namespace, every object is a model. For example, complex types
Order are all models defined in the namespace. You pass these models, with values, as parameters as shown in the following example. The example passes the
Address model as a parameter to create a new customer.
The Square API endpoints can have path parameters, query parameters, and a request body. When you make corresponding method calls using the Square Java SDK, you provide the values as follows:
Request body - For example,
Customerobject in the body. In the Square Java SDK, you use the builder pattern to specify the request body.
Path and query parameters - For example:
- The RetrieveCustomer endpoint has a
customer_idpath parameter (
- The ListCustomers endpoint has several query parameters such as
You provide these as parameters to the method calls. The following example passes the
customer_idpath parameter as a parameter to the
For an example of query parameters, see Pagination.
- The RetrieveCustomer endpoint has a
You can configure the number of retries and the timeout values for HTTP requests when using the Square Java SDK:
Retries - By default, the Square SDK doesn't retry a failed request. When your application starts, the Square SDK sets the number of retries to 0. You have the option to configure a different value when you create a client. Retries can help improve application stability by allowing applications to handle momentary failures in connecting to a service by transparently retrying a failed request.
Timeout - Timeout is the time period that a client waits for a server response. The Square SDK sets the default timeout to 60 seconds. On timeout, the SDK throws an exception. You have the option to configure a timeout value at the client level.
The following code creates a client, setting the number of retries to 2 and the timeout to 60 seconds.
Configuring a client with long timeout values and a high number of retries can cause some SDK operations to appear unresponsive. There are several considerations that apply when configuring the timeout and retries. These include:
- For network issues (decrease in network connectivity and response speed), how should the application respond? Do you want the call to fail fast, or do you want the application to retry the failed call?
- Buyer-facing applications might need to be responsive compared to a background job that can tolerate increased latency due increased timeout values and retries.
The response object contains the
HttpContext that describes both the request and the response.
- If an API call succeeds, a response object containing
HttpContextis returned. This
HttpContextdescribes both the request and the response.
- If an API call fails, you get an
ApiException(see ApiException class).
For more information, see Square API errors.