Package org.forgerock.json.resource

Interface Connection

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractAsynchronousConnection, AbstractConnectionWrapper

public interface Connection
extends Closeable

A client connection to a JSON resource provider over which read and update requests may be performed.

Method Summary

Modifier and Type	Method	Description
ActionResponse	action(Context context, ActionRequest request)	Performs an action against a specific resource, or set of resources.
Promise<ActionResponse,ResourceException>	actionAsync(Context context, ActionRequest request)	Asynchronously performs an action against a specific resource, or set of resources.
void	close()	Releases any resources associated with this connection.
ResourceResponse	create(Context context, CreateRequest request)	Adds a new JSON resource.
Promise<ResourceResponse,ResourceException>	createAsync(Context context, CreateRequest request)	Asynchronously adds a new JSON resource.
ResourceResponse	delete(Context context, DeleteRequest request)	Deletes a JSON resource.
Promise<ResourceResponse,ResourceException>	deleteAsync(Context context, DeleteRequest request)	Asynchronously deletes a JSON resource.
boolean	isClosed()	Indicates whether or not this connection has been explicitly closed by calling close.
boolean	isValid()	Returns true if this connection has not been closed and no fatal errors have been detected.
ResourceResponse	patch(Context context, PatchRequest request)	Updates a JSON resource by applying a set of changes to its existing content.
Promise<ResourceResponse,ResourceException>	patchAsync(Context context, PatchRequest request)	Asynchronously updates a JSON resource by applying a set of changes to its existing content.
QueryResponse	query(Context context, QueryRequest request, Collection<? super ResourceResponse> results)	Searches for all JSON resources matching a user specified set of criteria, and places the results in the provided collection.
QueryResponse	query(Context context, QueryRequest request, QueryResourceHandler handler)	Searches for all JSON resources matching a user specified set of criteria, and returns a Promise that will be completed with the results of the search.
Promise<QueryResponse,ResourceException>	queryAsync(Context context, QueryRequest request, QueryResourceHandler handler)	Asynchronously searches for all JSON resources matching a user specified set of criteria, and returns a Promise that will be completed with the results of the search.
ResourceResponse	read(Context context, ReadRequest request)	Reads a JSON resource.
Promise<ResourceResponse,ResourceException>	readAsync(Context context, ReadRequest request)	Asynchronously reads a JSON resource.
ResourceResponse	update(Context context, UpdateRequest request)	Updates a JSON resource by replacing its existing content with new content.
Promise<ResourceResponse,ResourceException>	updateAsync(Context context, UpdateRequest request)	Asynchronously updates a JSON resource by replacing its existing content with new content.

Method Detail

action

ActionResponse action(Context context,
                      ActionRequest request)
               throws ResourceException

Performs an action against a specific resource, or set of resources. Bulk updates are an example of an action request.

Parameters:

context - The request context, such as associated principal.

request - The action request.

Returns:

A JSON object containing the result of the action, the content of which is specified by the action.

Throws:

ResourceException - If the action could not be performed.

UnsupportedOperationException - If this connection does not support action requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

actionAsync

Promise<ActionResponse,ResourceException> actionAsync(Context context,
                                                            ActionRequest request)

Asynchronously performs an action against a specific resource, or set of resources. Bulk updates are an example of an action request.

Parameters:

context - The request context, such as associated principal.

request - The action request.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support action requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

close

void close()

Releases any resources associated with this connection. For physical connections to a server this will mean that the underlying socket is closed.

Other connection implementations may behave differently. For example, a pooled connection will be released and returned to its connection pool.

Calling close on a connection that is already closed has no effect.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

create

ResourceResponse create(Context context,
                        CreateRequest request)
                 throws ResourceException

Adds a new JSON resource.

Parameters:

context - The request context, such as associated principal.

request - The create request.

Returns:

The newly created JSON resource.

Throws:

ResourceException - If the JSON resource could not be created.

UnsupportedOperationException - If this connection does not support create requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

createAsync

Promise<ResourceResponse,ResourceException> createAsync(Context context,
                                                              CreateRequest request)

Asynchronously adds a new JSON resource.

Parameters:

context - The request context, such as associated principal.

request - The create request.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support create requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

delete

ResourceResponse delete(Context context,
                        DeleteRequest request)
                 throws ResourceException

Deletes a JSON resource.

Parameters:

context - The request context, such as associated principal.

request - The delete request.

Returns:

The deleted JSON resource.

Throws:

ResourceException - If the JSON resource could not be deleted.

UnsupportedOperationException - If this connection does not support delete requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

deleteAsync

Promise<ResourceResponse,ResourceException> deleteAsync(Context context,
                                                              DeleteRequest request)

Asynchronously deletes a JSON resource.

Parameters:

context - The request context, such as associated principal.

request - The delete request.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support delete requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

isClosed

boolean isClosed()

Indicates whether or not this connection has been explicitly closed by calling close. This method will not return true if a fatal error has occurred on the connection unless close has been called.

Returns:

true if this connection has been explicitly closed by calling close, or false otherwise.

isValid

boolean isValid()

Returns true if this connection has not been closed and no fatal errors have been detected. This method is guaranteed to return false only when it is called after the method close has been called.

Returns:

true if this connection is valid, false otherwise.

patch

ResourceResponse patch(Context context,
                       PatchRequest request)
                throws ResourceException

Updates a JSON resource by applying a set of changes to its existing content.

Parameters:

context - The request context, such as associated principal.

request - The update request.

Returns:

The updated JSON resource.

Throws:

ResourceException - If the JSON resource could not be updated.

UnsupportedOperationException - If this connection does not support patch requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

patchAsync

Promise<ResourceResponse,ResourceException> patchAsync(Context context,
                                                             PatchRequest request)

Asynchronously updates a JSON resource by applying a set of changes to its existing content.

Parameters:

context - The request context, such as associated principal.

request - The patch request.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support patch requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

query

QueryResponse query(Context context,
                    QueryRequest request,
                    QueryResourceHandler handler)
             throws ResourceException

Searches for all JSON resources matching a user specified set of criteria, and returns a Promise that will be completed with the results of the search.

Result processing happens-before this method returns to the caller.

Parameters:

context - The request context, such as associated principal.

request - The query request.

handler - A query resource handler which can be used to process matching resources as they are received.

Returns:

The query result.

Throws:

ResourceException - If the query could not be performed.

UnsupportedOperationException - If this connection does not support query requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

query

QueryResponse query(Context context,
                    QueryRequest request,
                    Collection<? super ResourceResponse> results)
             throws ResourceException

Searches for all JSON resources matching a user specified set of criteria, and places the results in the provided collection.

Parameters:

context - The request context, such as associated principal.

request - The query request.

results - A collection into which matching resources will be added as they are received.

Returns:

The query result.

Throws:

ResourceException - If the query could not be performed.

UnsupportedOperationException - If this connection does not support query requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

queryAsync

Promise<QueryResponse,ResourceException> queryAsync(Context context,
                                                          QueryRequest request,
                                                          QueryResourceHandler handler)

Asynchronously searches for all JSON resources matching a user specified set of criteria, and returns a Promise that will be completed with the results of the search.

Result processing happens-before the returned future completes.

Parameters:

context - The request context, such as associated principal.

request - The create request.

handler - A non-null query resource handler which should be used to process matching resources as they are received.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support query requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

read

ResourceResponse read(Context context,
                      ReadRequest request)
               throws ResourceException

Reads a JSON resource.

Parameters:

context - The request context, such as associated principal.

request - The read request.

Returns:

The JSON resource.

Throws:

ResourceException - If the JSON resource could not be read.

UnsupportedOperationException - If this connection does not support read requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

readAsync

Promise<ResourceResponse,ResourceException> readAsync(Context context,
                                                            ReadRequest request)

Asynchronously reads a JSON resource.

Parameters:

context - The request context, such as associated principal.

request - The read request.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support read requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

update

ResourceResponse update(Context context,
                        UpdateRequest request)
                 throws ResourceException

Updates a JSON resource by replacing its existing content with new content.

Parameters:

context - The request context, such as associated principal.

request - The update request.

Returns:

The updated JSON resource.

Throws:

ResourceException - If the JSON resource could not be updated.

UnsupportedOperationException - If this connection does not support update requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

updateAsync

Promise<ResourceResponse,ResourceException> updateAsync(Context context,
                                                              UpdateRequest request)

Asynchronously updates a JSON resource by replacing its existing content with new content.

Parameters:

context - The request context, such as associated principal.

request - The update request.

Returns:

A future representing the result of the request.

Throws:

UnsupportedOperationException - If this connection does not support update requests.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.