java.asc #11

=== Java SDK Reference

The Java SDK uses the `ApiClient` to initialize and configure access to the server.
From the `ApiClient` object, you obtain interfaces to access the individual methods.
The two interfaces are `DefaultApi`, which contain stable methods, and the `AlphaApi`, which are unstable methods (i.e., likely to change in future releases).

The Java SDK requires Java 8.

==== Getting Started

. Setup dependencies.
+
In the `clients/java/lib` directory is our Jar and all of it's dependencies.
Include these jars in your application's classpath to start running.
+
. Create an instance of `ApiClient`
+
[source,java]
....
ApiClient apiClient = new ApiClient(true, "https://mycompany.example.com");
....
+
WARNING: The example code above creates an object that *does not* validate SSL certificates.
For production code, you can use the simpler one argument variation, `new ApiClient("https://mycompany.example.com")`
+
. Create a handle to one of the API interfaces.
+
[source, java]
....
DefaultApi defaultApi = apiClient.createDefaultService();
....
+
INFO: For access to less stable methods, use `AlphaApi alphaApi = apiClient.createService(AlphaApi.class)`
+
. Obtain an authenticated ApiClient logged in to HWS_P4D_AUTH.
+
[source,java]
....
ApiClient apiClient = ApiClient.createWithTicket("https://mycompany.example.com", "jdoe", "johndoe1A!")
DefaultApi defaultApi = apiClient.createDefaultService();
....
+
. Log in to a specific P4D.
+
[source,java]
....
ApiClient apiClient = new ApiClient("https://mycompany.example.com");
apiClient.setCredentials("jdoe", "johndoe1A!");
DefaultApi defaultApi = apiClient.createDefaultService();
defaultApi.serverLogin("p4dName");
....
+
. Use the API interface for interacting with the server.
+
[source, java]
....
// This is a typical "command-style" method that returns results similar to
// the output of "p4 depots".
List<DepotsCommand> depots = api.serverDepotsGet("myserver");

// Methods that operate on specifications typically return "Spec" model types,
// in this case, based on the `p4 user -o jdoe` command.
UserCommand user = api.serverUsersUserGet(p4dId, "jdoe");
....

==== ApiClient Reference

[[java-api-client-static-create-with-ticket]]
===== ApiClient.createWithTicket

Create an ApiClient and sign into a Helix Web Services server.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
ApiClient ApiClient.createWithTicket(String baseUrl, String user, String password)
....

.Parameters
[cols="3*", options="header"]
|===
| Type
| Name
| Description

| `String`
| `baseUrl`
| The Helix Web Services base URL, e.g., "https://mycompany.example.com"

| `String`
| `user`
| The user login.
  If you have a multiple p4d configuration in your web services, this login is used against all servers.

| `String`
| `password`
| The user's password.
  If you have a multiple p4d configuration, this password is used against all servers.
|===

[source,java]
.Java Example
....
ApiClient apiClient = ApiClient.createWithTicket("https://myserver.example.com", "jdoe", "jdoePassword");
....



[[java-api-client-constructor]]
===== ApiClient Constructors

[[java-api-client-constructor-2]]
====== ApiClient#ApiClient(String basePath)

Construct an ApiClient with the indicated basePath.

If you are testing out a new installation, this will likely not work due
to the use of a self-signed certificate on the server.

WARNING: This ApiClient is *not* authenticated after construction.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
ApiClient(String basePath)
....

.Parameters
[cols="3*", options="header"]
|===
| Type
| Name
| Description

| `String`
| `basePath`
| The base URL to Helix Web Services instance, e.g., `https://myserver.example.com`.
|===

[source,java]
.Java Example
....
ApiClient apiClient = new ApiClient("https://myserver.example.com");
....



[[java-api-client-constructor-1]]
====== ApiClient#ApiClient(boolean trustAllSsl, String basePath)

A special construction option that allows your client to trust all certificates.

By default, all HWS instances start with a self-signed certificate.
You may need to construct using this variation to validate your code is working in a non-production system.

WARNING: This ApiClient is *not* authenticated after construction.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
ApiClient(boolean trustAllSsl, String basePath)
....

.Parameters
[cols="3*", options="header"]
|===
| Type
| Name
| Description

| `boolean`
| `trustAllSsl`
| When `true`, we'll disable all SSL/TLS certificate verification.
  This may be needed for testing with self-signed certificates, though we recommend avoiding this in production.

| `String`
| `basePath`
| The base URL to Helix Web Services instance, e.g., `https://myserver.example.com`.
|===

[source,java]
.Java Example
....
// Create a very insecure ApiClient.
ApiClient apiClient = new ApiClient(true, "https://myserver.example.com");
....

[[java-api-client-create-default-service]]
===== ApiClient#createDefaultService

Obtain a handle to the service interface for stable methods.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
DefaultApi ApiClient#createDefaultService(boolean trustAllSsl, String basePath)
....

.Returns
[cols="2*", options="header"]
|===
| Type
| Notes

| <<java-default-api>>
| The main interface your application should use to interact with Helix Web Services.
|===


[[java-api-client-create-service]]
===== ApiClient#createService

Obtain a handle to a service interface.
This can specify any particular API, such as the <<java-alpha-api>>.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
API ApiClient#createService(Class<API> interfaceName)
....

.Parameters
[cols="3*", options="header"]
|===
| Type
| Name
| Description

| Class<API>
| serviceClass
| The interface class to use.
|===

.Returns
[cols="2*", options="header"]
|===
| Type
| Notes

| The object handle that is the type specified by the parameter.
| The main interface your application should use to interact with Helix Web Services.
|===

[source,java]
.Java Example
....
AlphaApi alphaApi = apiClient.createService(AlphaApi.class);
....


[[java-api-client-get-base-path]]
===== ApiClient#getBasePath

Returns the base URL to your HWS instance.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
String ApiClient#getBasePath()
....

.Returns
[cols="2*", options="header"]
|===
| Type
| Notes

| String
| The base URL that's generally been specified by the constructor.
|===

[source,java]
.Java Example
....
String url = apiClient.getBasePath();
....


[[java-api-client-get-status]]
===== ApiClient#getStatus

Returns the current status of the system.
Unlike the <<java-api-client-is-ok>> method, this *will* throw an exception in the face of any kind of network failure.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
HWSStatus ApiClient#getStatus()
....

.Returns
[cols="2*", options="header"]
|===
| Type
| Notes

| <<java-model-h-w-s-status>>
|
|===


[[java-api-client-is-ok]]
===== ApiClient#isOK

Checks the status and returns true if Helix Web Services is responding and doesn't report any problems.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
boolean ApiClient#isOK()
....

.Returns
[cols="2*", options="header"]
|===
| Type
| Notes

| boolean
| True if HWS responds, false otherwise.
  We generally will *not* throw exceptions in the face of failures.
|===

[source,java]
.Java Example
....
if (!apiClient.isOK()) {
    throw new IllegalStateException("Helix Web Services is not available");
}
....

[[java-api-client-is-supported]]
===== ApiClient#isSupported

Will fetch the supported list of versions from the Helix Web Services server, and verify if this Client SDK version is supported by this server.
In general, it's probably a good idea to use this method when configuring a new Helix Web Services server, in order to say, let the user know if they need to upgrade their application.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
boolean ApiClient#isSupported()
....

.Returns
[cols="2*", options="header"]
|===
| Type
| Notes

| boolean
| True if the client is supported, false if it's not or there's any kind of problem connecting to the server.
|===

[source,java]
.Java Example
....
if (!apiClient.isSupported()) {
    throw new IllegalStateException("Helix Web Services doees not support this client version or is not available");
}
....

[[java-api-client-set-api-key]]
===== ApiClient#setApiKey

Sets the per-user authentication ticket to use for access to Helix Web Services.

.Package Name
[source,java]
....
com.perforce.hwsclient
....

.Method Signature
[source,java]
....
void ApiClient#setApiKey(String apiKey)
....

.Parameters
[cols="1,1,2a", options="header"]
|===
| Type
| Name
| Description

| String
| apiKey
| The ticket value of the <<java-model-login-response>>.
|===


[[java-default-api]]
==== DefaultApi Reference

include::../java-default.adoc[]

[[java-alpha-api]]
==== AlphaApi Reference

include::../java-alpha.adoc[]

[[java-model]]
==== Java Models

Each Java model provides getter and setter accessor methods to each listed property name.

include::../java-models.adoc[]