Package org.forgerock.json.resource

Class AbstractConnectionWrapper<C extends Connection>

java.lang.Object

org.forgerock.json.resource.AbstractConnectionWrapper<C>

Type Parameters:

C - The type of wrapped connection.

All Implemented Interfaces:

Closeable, AutoCloseable, Connection, Describable<org.forgerock.api.models.ApiDescription,Request>

public abstract class AbstractConnectionWrapper<C extends Connection>
extends Object
implements Connection, Describable<org.forgerock.api.models.ApiDescription,Request>

An abstract base class from which connection wrappers may be easily implemented. The default implementation of each method is to delegate to the wrapped connection.

Nested Class Summary

Nested classes/interfaces inherited from interface org.forgerock.services.descriptor.Describable

Describable.Listener

Field Summary

Fields

Modifier and Type	Field	Description
protected C	connection	The wrapped connection.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractConnectionWrapper(C connection)	Creates a new connection wrapper.

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	addDescriptorListener(Describable.Listener listener)	Add a listener for API Descriptor changes.
org.forgerock.api.models.ApiDescription	api(ApiProducer<org.forgerock.api.models.ApiDescription> producer)	Provide the API description for the component.
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.
org.forgerock.api.models.ApiDescription	handleApiRequest(Context context, Request request)	Handle a request for the API Descriptor.
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.
void	removeDescriptorListener(Describable.Listener listener)	Remove a listener from API Descriptor changes.
protected Context	transform(Context context)	Optional Context-transformation function if the implementer has requirements to override the Context provided in the Connection's method invocations.
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.

Methods inherited from class java.lang.Object

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

Field Detail

connection

protected final C extends Connection connection

The wrapped connection.

Constructor Detail

AbstractConnectionWrapper

protected AbstractConnectionWrapper(C connection)

Creates a new connection wrapper.

Parameters:

connection - The connection to be wrapped.

Method Detail

transform

protected Context transform(Context context)

Optional Context-transformation function if the implementer has requirements to override the Context provided in the Connection's method invocations.

The default implementation is a pass-through no-op.

Parameters:

context - the request context

Returns:

the transformed context

action

public 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.

The default implementation is to delegate.

Specified by:

action in interface Connection

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.

actionAsync

public 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.

The default implementation is to delegate.

Specified by:

actionAsync in interface Connection

Parameters:

context - The request context, such as associated principal.

request - The action request.

Returns:

A future representing the result of the request.

close

public 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.

The default implementation is to delegate.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface Connection

create

public ResourceResponse create(Context context,
                               CreateRequest request)
                        throws ResourceException

Adds a new JSON resource.

The default implementation is to delegate.

Specified by:

create in interface Connection

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.

createAsync

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

Asynchronously adds a new JSON resource.

The default implementation is to delegate.

Specified by:

createAsync in interface Connection

Parameters:

context - The request context, such as associated principal.

request - The create request.

Returns:

A future representing the result of the request.

delete

public ResourceResponse delete(Context context,
                               DeleteRequest request)
                        throws ResourceException

Deletes a JSON resource.

The default implementation is to delegate.

Specified by:

delete in interface Connection

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.

deleteAsync

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

Asynchronously deletes a JSON resource.

The default implementation is to delegate.

Specified by:

deleteAsync in interface Connection

Parameters:

context - The request context, such as associated principal.

request - The delete request.

Returns:

A future representing the result of the request.

isClosed

public 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.

The default implementation is to delegate.

Specified by:

isClosed in interface Connection

Returns:

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

isValid

public 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.

The default implementation is to delegate.

Specified by:

isValid in interface Connection

Returns:

true if this connection is valid, false otherwise.

patch

public ResourceResponse patch(Context context,
                              PatchRequest request)
                       throws ResourceException

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

The default implementation is to delegate.

Specified by:

patch in interface Connection

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.

patchAsync

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

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

The default implementation is to delegate.

Specified by:

patchAsync in interface Connection

Parameters:

context - The request context, such as associated principal.

request - The patch request.

Returns:

A future representing the result of the request.

query

public 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.

The default implementation is to delegate.

Specified by:

query in interface Connection

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.

query

public 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.

The default implementation is to delegate.

Specified by:

query in interface Connection

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.

queryAsync

public 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.

The default implementation is to delegate.

Specified by:

queryAsync in interface Connection

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.

read

public ResourceResponse read(Context context,
                             ReadRequest request)
                      throws ResourceException

Reads a JSON resource.

The default implementation is to delegate.

Specified by:

read in interface Connection

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.

readAsync

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

Asynchronously reads a JSON resource.

The default implementation is to delegate.

Specified by:

readAsync in interface Connection

Parameters:

context - The request context, such as associated principal.

request - The read request.

Returns:

A future representing the result of the request.

update

public ResourceResponse update(Context context,
                               UpdateRequest request)
                        throws ResourceException

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

The default implementation is to delegate.

Specified by:

update in interface Connection

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.

updateAsync

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

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

The default implementation is to delegate.

Specified by:

updateAsync in interface Connection

Parameters:

context - The request context, such as associated principal.

request - The update request.

Returns:

A future representing the result of the request.

api

public org.forgerock.api.models.ApiDescription api(ApiProducer<org.forgerock.api.models.ApiDescription> producer)

Description copied from interface: Describable

Provide the API description for the component. This method should perform the heavy-lifting of computing the API descriptor, and should be expected to be called rarely. Upstream handlers should call this method in order to compose all of their downstream API Descriptors into a single descriptor.

Specified by:

api in interface Describable<org.forgerock.api.models.ApiDescription,Request>

Parameters:

producer - The API producer that provides general information to be built into the descriptor.

Returns:

The description object.

handleApiRequest

public org.forgerock.api.models.ApiDescription handleApiRequest(Context context,
                                                                Request request)

Description copied from interface: Describable

Handle a request for the API Descriptor. This method should not do any computation, but should return the already computed descriptor.

Specified by:

handleApiRequest in interface Describable<org.forgerock.api.models.ApiDescription,Request>

Parameters:

context - The request context.

request - The request.

Returns:

The descriptor.

addDescriptorListener

public void addDescriptorListener(Describable.Listener listener)

Description copied from interface: Describable

Add a listener for API Descriptor changes. The described object should call all the listeners.

Specified by:

addDescriptorListener in interface Describable<org.forgerock.api.models.ApiDescription,Request>

Parameters:

listener - The listener.

removeDescriptorListener

public void removeDescriptorListener(Describable.Listener listener)

Description copied from interface: Describable

Remove a listener from API Descriptor changes.

Specified by:

removeDescriptorListener in interface Describable<org.forgerock.api.models.ApiDescription,Request>

Parameters:

listener - The listener.