com.rallydev.rest

Class RallyRestApi

java.lang.Object

com.rallydev.rest.RallyRestApi

All Implemented Interfaces:

Closeable, AutoCloseable

public class RallyRestApi
extends Object
implements Closeable

The main interface to the Rest API.

Provides CRUD and query operations.

Field Summary

Fields

Modifier and Type	Field and Description
protected HttpClient	client

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RallyRestApi(HttpClient httpClient)
	RallyRestApi(URI server, String apiKey) Creates a new instance for the specified server using the specified API Key.
	RallyRestApi(URI server, String userName, String password) Deprecated. Use the api key constructor instead.

Method Summary

Modifier and Type	Method and Description
void	close() Release all resources associated with this instance.
CreateResponse	create(CreateRequest request) Create the specified object.
DeleteResponse	delete(DeleteRequest request) Delete the specified object.
GetResponse	get(GetRequest request) Get the specified object.
HttpClient	getClient() Get the underlying http client implementation.
String	getWsapiVersion() Get the current version of the WSAPI being targeted.
QueryResponse	query(QueryRequest request) Query for objects matching the specified request.
void	setApplicationName(String value) Set the value of the X-RallyIntegrationName header included on all requests.
void	setApplicationVendor(String value) Set the value of the X-RallyIntegrationVendor header included on all requests.
void	setApplicationVersion(String value) Set the value of the X-RallyIntegrationVersion header included on all requests.
void	setProxy(URI proxy) Set the unauthenticated proxy server to use.
void	setProxy(URI proxy, String userName, String password) Set the authenticated proxy server to use.
void	setWsapiVersion(String wsapiVersion) Set the current version of the WSAPI being targeted.
UpdateResponse	update(UpdateRequest request) Update the specified object.
CollectionUpdateResponse	updateCollection(CollectionUpdateRequest request) Update the specified collection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

client

protected HttpClient client

Constructor Detail

RallyRestApi

public RallyRestApi(URI server,
                    String userName,
                    String password)

Deprecated. Use the api key constructor instead.

Creates a new instance for the specified server using the specified credentials.

Parameters:

server - The server to connect to, e.g. new URI("https://rally1.rallydev.com")

userName - The username to be used for authentication.

password - The password to be used for authentication.

RallyRestApi

public RallyRestApi(URI server,
                    String apiKey)

Creates a new instance for the specified server using the specified API Key.

Parameters:

server - The server to connect to, e.g. new URI("https://rally1.rallydev.com")

apiKey - The API Key to be used for authentication.

RallyRestApi

protected RallyRestApi(HttpClient httpClient)

Method Detail

setProxy

public void setProxy(URI proxy)

Set the unauthenticated proxy server to use. By default no proxy is configured.

Parameters:

proxy - The proxy server, e.g. new URI("http://my.proxy.com:8000")

setProxy

public void setProxy(URI proxy,
                     String userName,
                     String password)

Set the authenticated proxy server to use. By default no proxy is configured.

Parameters:

proxy - The proxy server, e.g. new URI("http://my.proxy.com:8000")

userName - The username to be used for authentication.

password - The password to be used for authentication.

setApplicationVendor

public void setApplicationVendor(String value)

Set the value of the X-RallyIntegrationVendor header included on all requests. This should be set to your company name.

Parameters:

value - The vendor header to be included on all requests.

setApplicationVersion

public void setApplicationVersion(String value)

Set the value of the X-RallyIntegrationVersion header included on all requests. This should be set to the version of your application.

Parameters:

value - The vendor header to be included on all requests.

setApplicationName

public void setApplicationName(String value)

Set the value of the X-RallyIntegrationName header included on all requests. This should be set to the name of your application.

Parameters:

value - The vendor header to be included on all requests.

getWsapiVersion

public String getWsapiVersion()

Get the current version of the WSAPI being targeted. Defaults to v2.0

Returns:

the current WSAPI version.

setWsapiVersion

public void setWsapiVersion(String wsapiVersion)

Set the current version of the WSAPI being targeted.

Parameters:

wsapiVersion - the new version, e.g. "1.30"

create

public CreateResponse create(CreateRequest request)
                      throws IOException

Create the specified object.

Parameters:

request - the CreateRequest specifying the object to be created.

Returns:

the resulting CreateResponse

Throws:

IOException - if an error occurs during the creation.

update

public UpdateResponse update(UpdateRequest request)
                      throws IOException

Update the specified object.

Parameters:

request - the UpdateRequest specifying the object to be updated.

Returns:

the resulting UpdateResponse

Throws:

IOException - if an error occurs during the update.

updateCollection

public CollectionUpdateResponse updateCollection(CollectionUpdateRequest request)
                                          throws IOException

Update the specified collection. Note that this method is only usable with WSAPI versions 2.0 and above.

Parameters:

request - the CollectionUpdateRequest specifying the collection to be updated.

Returns:

the resulting CollectionUpdateResponse

Throws:

IOException - if an error occurs during the update.

delete

public DeleteResponse delete(DeleteRequest request)
                      throws IOException

Delete the specified object.

Parameters:

request - the DeleteRequest specifying the object to be deleted.

Returns:

the resulting DeleteResponse

Throws:

IOException - if an error occurs during the deletion.

query

public QueryResponse query(QueryRequest request)
                    throws IOException

Query for objects matching the specified request. By default one page of data will be returned. Paging will automatically be performed if a limit is set on the request.

Parameters:

request - the QueryRequest specifying the object to be created.

Returns:

the resulting QueryResponse

Throws:

IOException - if an error occurs during the query.

get

public GetResponse get(GetRequest request)
                throws IOException

Get the specified object.

Parameters:

request - the GetRequest specifying the object to be retrieved.

Returns:

the resulting GetResponse

Throws:

IOException - if an error occurs during the retrieval.

close

public void close()
           throws IOException

Release all resources associated with this instance.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if an error occurs releasing resources

getClient

public HttpClient getClient()

Get the underlying http client implementation. This is exposed with the intent of providing the ability to supply additional configuration to the client. It should not be used to directly make i/o calls.

Returns:

the raw http client