atg.service.jaxrs

Class RestUtils

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.service.jaxrs.RestUtils

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener

public class RestUtils
extends GenericService

Utility class for functions used by REST operations.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string.
static java.lang.String	DEFAULT_REST_UTILS_PATH Default path to a configuration instance of this service
static java.lang.String	ID_PROPERTY
static java.lang.String	REST_REQUEST_DATA_KEY_PREFIX The prefix added to request data.
protected static RestUtils	sDefaultRestUtils

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Constructors

Constructor and Description
RestUtils()

Method Summary

Modifier and Type	Method and Description
void	addRestRequestData(java.lang.String pKey, java.lang.Object pValue) Store data for the rest request.
java.lang.String[]	buildPageMembersUris(ListingResponse pListingResponse, <any> pQueryParams, java.lang.String pIdPropertyName) Returns string uri(s) for member(s) based on the ListingResponse items.
RestException	createException(int pStatus, java.lang.String pMessage) Set an error for this request.
RestException	createException(int pStatus, java.lang.String pMessage, java.util.List<java.lang.Exception> pErrors) Set an error containing multiple error messages.
RestException	createException(int pStatus, java.lang.String pErrorCode, java.lang.String pMessage, java.lang.String pDevMessage, java.lang.String pMoreInfo, java.lang.Throwable pRootCause, java.util.List<java.lang.Exception> pAllErrors) Set an error for this request.
RestException	createException(java.lang.String pMessage) Set an error for this request.
RestException	createException(java.lang.String pErrorCode, java.lang.String pMessage, java.lang.String pDevMessage, java.lang.String pMoreInfo) Set an error for this request, default to using status 500.
RestException	createException(java.lang.String pMessage, java.lang.Throwable pRootCause) Set an error for this request, default to using status 500.
RestException	createException(java.lang.Throwable pException) Handle an error during the doAction() method and build a jaxrs exception.
int	determineResourceVersion(java.lang.Object pVersionedObject) Utility method an endpoint may use to invoke the ETag service to try and determine a version for the given object.
RestResourceRegistry	getCurrentRegistry() Utility method to retrieve the current registry in context
java.lang.String	getCurrentResourceId() Gets the id of the current resource in context.
java.lang.String	getDefaultCurie()
java.util.Map<java.lang.String,java.lang.Object>	getErrorAttributes(java.lang.Throwable pCurrentException, java.util.Set<java.lang.Throwable> pProcessedExceptions)
atg.service.jaxrs.RestExceptionRegistry	getExceptionRegistry() Return exceptionRegistry.
ListingRequest	getListingRequest(int pDefaultLimit) Utility method to build the listing request.
JAXRSApplication	getMatchingApplication(java.lang.String pUriPath)
RepresentationModel.Builder	getModelBuilderWithPaging(int pDefResourcePageSize, boolean pSortAllowed, java.lang.String pIdPropertyName, <any> pQueryParams, java.util.Collection pMembers) Build the model with the members set to a page of the given collection (list/set) and the ListingResponse for pagination set.
RepresentationModel.Builder	getModelBuilderWithPaging(int pDefaultResourcePageSize, java.lang.String pIdPropertyName, <any> pQueryParams, java.lang.String... pMembersIds) Build the model with the members set to a page of the given array and the ListingResponse for pagination set.
RelationsRegistry	getRelationsRegistry() Reference to the relations registry that can be used to access curie details or other relation data.
Response	getResource(java.lang.String pRelName, java.lang.String pResourceURI, java.lang.String pUseValidatorId, int pFilterDepth, boolean pCrossRegistryURI) Uses the internal client to call into Jersey and retrieve a resource representation for the given resource URI.
java.lang.Object	getResourceReference(java.lang.String pResourceId) Utility method to get a reference to a resource by its id.
atg.service.jaxrs.RestUpdateInfo.RestResourceUpdateInfo	getResourceUpdateInfo() Utility method to the ResourceUpdateInfo for the current request
java.lang.Object	getRestRequestData(java.lang.String pKey) Get rest request data.
static RestUtils	getRestUtils() //---------------------------------------- Static method to get an instance of this component.
java.lang.Object	getRootResource() Utility method to return the resource representation for the root resource of the request in context.
java.lang.String	getRootResourcePath() Utility method to get the string uri path for the singular root resource of the current request resource.
protected java.sql.SQLException	getSQLException(java.lang.Throwable pException) Recursively searches the exception for a SQLException.
boolean	isTemplatedPath(java.lang.String pPath) Utility method to determine if the given path string has any templated parts, e.g.
void	setExceptionRegistry(atg.service.jaxrs.RestExceptionRegistry pExceptionRegistry) Set exceptionRegistry.
void	setRelationsRegistry(RelationsRegistry pRelationsRegistry) Reference to the relations registry that can be used to access curie details or other relation data.
boolean	shouldLogError(int pStatusCode) Check to see if we should log the given error.
void	sortListingResponse(ListingResponse pListingResponse) Sort the ListingResponse collection if the orderBy or sortBy param was set.
void	streamState(java.io.OutputStream pStream, byte[] pStateBinary) Write the state information passed in pState to the output stream passed in pStream.
void	streamState(java.io.OutputStream pStream, java.lang.String pState) Write the state information passed in pState to the output stream passed in pStream.
RestException	toRestException(java.lang.Throwable pOriginatingException)
void	validateInputObject(java.lang.Object pInputObject) Utility method to invoke validation of an input object.
void	validateInputObject(java.lang.Object pInputObject, java.lang.String pValidatorId) Utility method to invoke validation of an object using the specified validator

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService, toString

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string.

REST_REQUEST_DATA_KEY_PREFIX

public static final java.lang.String REST_REQUEST_DATA_KEY_PREFIX

The prefix added to request data.

See Also:

Constant Field Values

DEFAULT_REST_UTILS_PATH

public static final java.lang.String DEFAULT_REST_UTILS_PATH

Default path to a configuration instance of this service

See Also:

Constant Field Values

ID_PROPERTY

public static final java.lang.String ID_PROPERTY

See Also:

Constant Field Values

sDefaultRestUtils

protected static RestUtils sDefaultRestUtils

Constructor Detail

RestUtils

public RestUtils()

Method Detail

getRestUtils

public static RestUtils getRestUtils()

//---------------------------------------- Static method to get an instance of this component. Default implementation gets the instance from the current rest context.

Returns:

RestUtils instance to use.

getRelationsRegistry

public RelationsRegistry getRelationsRegistry()

Reference to the relations registry that can be used to access curie details or other relation data.

Returns:

RelationsRegistry reference

setRelationsRegistry

public void setRelationsRegistry(RelationsRegistry pRelationsRegistry)

Reference to the relations registry that can be used to access curie details or other relation data.

Parameters:

pRelationsRegistry - RelationsRegistry reference

setExceptionRegistry

public void setExceptionRegistry(atg.service.jaxrs.RestExceptionRegistry pExceptionRegistry)

Set exceptionRegistry. Exception registry contains mappings of Exception type to HTTP response code for building error response.

Parameters:

pExceptionRegistry - the exception registry property.

See Also:

RestExceptionRegistry

getExceptionRegistry

public atg.service.jaxrs.RestExceptionRegistry getExceptionRegistry()

Return exceptionRegistry. Exception registry contains mappings of Exception type to HTTP response code for building error response.

Returns:

the exception registry property.

createException

public RestException createException(int pStatus,
                                     java.lang.String pErrorCode,
                                     java.lang.String pMessage,
                                     java.lang.String pDevMessage,
                                     java.lang.String pMoreInfo,
                                     java.lang.Throwable pRootCause,
                                     java.util.List<java.lang.Exception> pAllErrors)

Set an error for this request.

Parameters:

pStatus - the http response status code ie 404, 500 etc.

pErrorCode - an internal application-specific error code

pMessage - the error message, suitable for display in a UI

pDevMessage - an optional developer-oriented error message to give more in-depth information about the error condition

pMoreInfo - an optional url link for additional information about the error condition

pRootCause - the root cause of the exception. May be null.

pAllErrors - other exceptions that have occurred along with this error

Returns:

The created exception using the info passed in.

createException

public RestException createException(int pStatus,
                                     java.lang.String pMessage,
                                     java.util.List<java.lang.Exception> pErrors)

Set an error containing multiple error messages.

Parameters:

pStatus - the http response status code ie 404, 500 etc.

pMessage - the optional general error message

pErrors - errors that have occurred, possibly more than one.

Returns:

The created exception using the info passed in.

createException

public RestException createException(java.lang.Throwable pException)

Handle an error during the doAction() method and build a jaxrs exception.
Note, if the passed in exception is a RestException then this is used.

Parameters:

pException - the exception to create jaxrs exception from.

Returns:

The created exception using the info passed in.

createException

public RestException createException(java.lang.String pMessage,
                                     java.lang.Throwable pRootCause)

Set an error for this request, default to using status 500.
Note, if the passed in root cause is a RestException then this is used and the passed in message is ignored.

Parameters:

pMessage - the error message, suitable for display in a UI

pRootCause - the root cause of the exception. May be null.

Returns:

The created exception using the info passed in.

toRestException

public RestException toRestException(java.lang.Throwable pOriginatingException)

getErrorAttributes

public java.util.Map<java.lang.String,java.lang.Object> getErrorAttributes(java.lang.Throwable pCurrentException,
                                                                           java.util.Set<java.lang.Throwable> pProcessedExceptions)

createException

public RestException createException(int pStatus,
                                     java.lang.String pMessage)

Set an error for this request.

Parameters:

pStatus - the http response status code ie 404, 500 etc.

pMessage - the error message, suitable for display in a UI

Returns:

The created exception using the info passed in.

createException

public RestException createException(java.lang.String pMessage)

Set an error for this request.

Parameters:

pMessage - the error message, suitable for display in a UI

Returns:

The created exception using the info passed in.

createException

public RestException createException(java.lang.String pErrorCode,
                                     java.lang.String pMessage,
                                     java.lang.String pDevMessage,
                                     java.lang.String pMoreInfo)

Set an error for this request, default to using status 500.

Parameters:

pErrorCode - an internal application-specific error code

pMessage - the error message, suitable for display in a UI

pDevMessage - an optional developer-oriented error message to give more in-depth information about the error condition

pMoreInfo - an optional url link for additional information about the error condition

Returns:

The created exception using the info passed in.

shouldLogError

public boolean shouldLogError(int pStatusCode)

Check to see if we should log the given error. Only internal errors with status codes 500+ should be logged. Otherwise we risk the logs being filled with client errors or other types of errors e.g. 304. Will return false if the current context is not for the top-level resource.

Parameters:

pStatusCode - the http response status code ie 404, 500 etc.

Returns:

Returns true if the error should be logged.

getSQLException

protected java.sql.SQLException getSQLException(java.lang.Throwable pException)

Recursively searches the exception for a SQLException. This is to handle reporting database issues in a friendlier way to the UI.

Parameters:

pException - root cause to build sql exception from.

Returns:

the sql exception

streamState

public void streamState(java.io.OutputStream pStream,
                        java.lang.String pState)
                 throws java.io.IOException

Write the state information passed in pState to the output stream passed in pStream. This method uses the @see RestConstants#ENCODING for encoding the string to bytes for the stream.

Parameters:

pStream - the output stream.

pState - the state information as a string.

Throws:

java.io.IOException - is an error occurs communicating with the stream.

streamState

public void streamState(java.io.OutputStream pStream,
                        byte[] pStateBinary)
                 throws java.io.IOException

Write the state information passed in pState to the output stream passed in pStream.

Parameters:

pStream - the output stream.

pStateBinary - the state information as an array of bytes.

Throws:

java.io.IOException - is an error occurs communicating with the stream.

getMatchingApplication

public JAXRSApplication getMatchingApplication(java.lang.String pUriPath)

getResource

public Response getResource(java.lang.String pRelName,
                            java.lang.String pResourceURI,
                            java.lang.String pUseValidatorId,
                            int pFilterDepth,
                            boolean pCrossRegistryURI)

Uses the internal client to call into Jersey and retrieve a resource representation for the given resource URI.

Parameters:

pRelName - String rel name that this resource will be embedded with

pResourceURI - URI to the resource. If it doesn't start with the context root then it is prepended automatically.

pUseValidatorId - the validator id to use for the specified embedded resource

pFilterDepth - the depth with which to filter the current resource

pCrossRegistryURI - true if pResourceURI may belong to a registry not currently in context

Returns:

Response representation of the resource

addRestRequestData

public void addRestRequestData(java.lang.String pKey,
                               java.lang.Object pValue)

Store data for the rest request. Allows storing data for the length of the request so that the data can be retrieved in sub-resource methods to avoid fetching the same data multiple times for a single request.

Parameters:

pKey - key to cache entry

pValue - object to cache

getRestRequestData

public java.lang.Object getRestRequestData(java.lang.String pKey)

Get rest request data. Data can be stored for the length of the request so that the data can be retrieved in sub-resource methods to avoid fetching the same data multiple times for a single request.

Parameters:

pKey - key to cache entry

Returns:

the cached value

getCurrentResourceId

public java.lang.String getCurrentResourceId()

Gets the id of the current resource in context.

Returns:

resource id for the resource currently in context

getCurrentRegistry

public RestResourceRegistry getCurrentRegistry()

Utility method to retrieve the current registry in context

Returns:

the current context rest resource registry

getDefaultCurie

public java.lang.String getDefaultCurie()

validateInputObject

public void validateInputObject(java.lang.Object pInputObject)

Utility method to invoke validation of an input object. The validator used will be determined by the ValidationService using the endpoint settings of the current request.

Parameters:

pInputObject - the object to validate

validateInputObject

public void validateInputObject(java.lang.Object pInputObject,
                                java.lang.String pValidatorId)

Utility method to invoke validation of an object using the specified validator

Parameters:

pInputObject - the object to validate

pValidatorId - the id of the validator to use

getResourceReference

public java.lang.Object getResourceReference(java.lang.String pResourceId)
                                      throws RestException

Utility method to get a reference to a resource by its id. For global/singleton scope resources the instance will be returned otherwise the class of the resource will be returned.

Parameters:

pResourceId - String id of the resource to get an reference to

Returns:

instance or class of the resource for the given id.

Throws:

RestException

getListingRequest

public ListingRequest getListingRequest(int pDefaultLimit)
                                 throws RestException

Utility method to build the listing request. It contains start, ending, sorting and offset properties of a request.

Parameters:

pDefaultLimit - page size limit to use if none is set

Returns:

the listing request

Throws:

RestException - the rest exception

getModelBuilderWithPaging

public RepresentationModel.Builder getModelBuilderWithPaging(int pDefaultResourcePageSize,
                                                             java.lang.String pIdPropertyName,
                                                             <any> pQueryParams,
                                                             java.lang.String... pMembersIds)
                                                      throws RestException

Build the model with the members set to a page of the given array and the ListingResponse for pagination set.

The array of string ids passed in are used to build the member uris.

Using the Listing classes this method supports the standard pagination limit & offset params. The orderBy param is not supported. The model's Listing Response is set so that the paging links will be shown correctly.

It also supports the getForUpdate param for PATCH merge - setting the ListingResponse items to the full collection, so ids can be output before and after the paged collection, thus not deleting unmodified items.

Parameters:

pDefaultResourcePageSize - the default page size for the calling resource

pIdPropertyName - identifies the collection item's property to use as the member's id

pQueryParams - Optional map of query param key/value pairs to be added to any built uris, null if none

pMembersIds - One or more string member instance ids

Returns:

the RepresentationModel.Builder with the paged members collection and ListingResponse set.

Throws:

RestException

getModelBuilderWithPaging

public RepresentationModel.Builder getModelBuilderWithPaging(int pDefResourcePageSize,
                                                             boolean pSortAllowed,
                                                             java.lang.String pIdPropertyName,
                                                             <any> pQueryParams,
                                                             java.util.Collection pMembers)
                                                      throws RestException

Build the model with the members set to a page of the given collection (list/set) and the ListingResponse for pagination set.

To build the member uris the collection object's property will be used as the member identifier. Otherwise the toString() method is used. Supporting a collection of repository items; beans or String.

Using the Listing classes this method supports the standard pagination limit & offset params. It supports the standard orderBy param if pSortAllowed is true. It also supports the getForUpdate param for PATCH merge - setting the ListingResponse items to the full collection. So ids can be output before and after the paged collection, thus not deleting unmodified items.

Pagination requires an ordered member collection to maintain consistency across calls. If the collection is unordered using offset > 0 or limit < collection size can produce a different collection of items for the same request.

To guarantee the same result ensure the members collection passed in is a list.

The members collection still supports a Set but the paged result will only be consistent if orderBy is also used. When orderBy is used the collection is converted to a list for sorting, it takes longer as the collection gets bigger.

Parameters:

pDefResourcePageSize - the default page size for the calling resource

pSortAllowed - indicates if calling resource should honor the orderBy param or ignore it

pIdPropertyName - identifies the collection item's property to use as the member's id

pQueryParams - Optional map of query param key/value pairs to be added to any built uris, null if none

pMembers - a collection (list/set) of resource members

Returns:

the RepresentationModel.Builder with the paged members collection and ListingResponse set.

Throws:

RestException

sortListingResponse

public void sortListingResponse(ListingResponse pListingResponse)

Sort the ListingResponse collection if the orderBy or sortBy param was set.

Supports sorting of List and Set collections by cloning the original collection. Collection is cloned as:

converting a set (unordered) to a list (ordered) allows it to be sorted creating a new list means we don't affect the order of the original repository/pojo collection held in memory.

The sort will take longer as the collection gets bigger.

Parameters:

pListingResponse - listing response used to build up the member URI from the paginated set of items

buildPageMembersUris

public java.lang.String[] buildPageMembersUris(ListingResponse pListingResponse,
                                               <any> pQueryParams,
                                               java.lang.String pIdPropertyName)

Returns string uri(s) for member(s) based on the ListingResponse items.

If the collection is already paged then the ListingResponse collection will be used. If the collection is not paged then the ListingResponse pagination settings will be used to return only the paged uris. Supports the ListingResponse holding either a List or Set collection.

Optionally a map of query params can also be passed in which will then be appended to any built uris.

Parameters:

pListingResponse - listing response used to build up the member URI from the paginated set of items

pQueryParams - Optional map of query param key/value pairs to be added to any built uris, null if none

Returns:

array of string uris for the given member ids.

getResourceUpdateInfo

public atg.service.jaxrs.RestUpdateInfo.RestResourceUpdateInfo getResourceUpdateInfo()
                                                                              throws RestException

Utility method to the ResourceUpdateInfo for the current request

Returns:

the ResourceUpdateInfo (may be null)

Throws:

RestException - the rest exception

determineResourceVersion

public int determineResourceVersion(java.lang.Object pVersionedObject)

Utility method an endpoint may use to invoke the ETag service to try and determine a version for the given object. For example, this will try and utilize the inherent version that may be available if the object is a repository item or is backed by a repository item (e.g. OrderImpl). Example usage might be a product collection endpoint determining the version of the collection as the version of the parent item, e.g. the parent category repository item.

Parameters:

pVersionedObject - Object for the resource that may contain an inherent version.

Returns:

int version or 0 if none was determined

getRootResourcePath

public java.lang.String getRootResourcePath()

Utility method to get the string uri path for the singular root resource of the current request resource. E.g. if the request is for /cart/commerceItems then this will return /cart or if the request was for /order/o1234/commerceItems then this will return /order/o1234

Returns:

String uri path for the root resource or null if not found

getRootResource

public java.lang.Object getRootResource()

Utility method to return the resource representation for the root resource of the request in context. E.g. if the current request is for /cart/commerceItems then this method will return the /cart RepresentationModel object by invoking the GET method of that root resource.

Returns:

Object representation of the root resource for the current request or null if none found.

isTemplatedPath

public boolean isTemplatedPath(java.lang.String pPath)

Utility method to determine if the given path string has any templated parts, e.g. '/orders/{orderId}' would return true but '/cart' would return false.

Parameters:

pPath - String path that may or may not have template variable parts.

Returns:

true if the path has template variables.