com.hp.util.rs

Class BaseResource

java.lang.Object

com.hp.util.rs.BaseResource

Direct Known Subclasses:

AgentAwareResource, FileSystemResource

public abstract class BaseResource
extends Object

Base REST resource implementation.

Author:

Thomas Vachuska, Steve Britt, Liem Nguyen

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	DATE_FORMAT
protected static String	DATETIME_FORMAT
protected static String	DEFAULT_USER
protected org.slf4j.Logger	log
static String	NAME
protected static javax.ws.rs.core.CacheControl	NO_CACHE Cache control descriptor to force no-caching.
static String	REF
protected javax.ws.rs.core.SecurityContext	security
static String	UID
protected javax.ws.rs.core.UriInfo	uriInfo

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BaseResource(org.slf4j.Logger log) Create a resource capable of logging to the specified logger.

Method Summary

Methods

Modifier and Type	Method and Description
javax.ws.rs.core.Response.ResponseBuilder	accepted() Create an accepted response (202) with no caching.
javax.ws.rs.core.Response.ResponseBuilder	accepted(URI location) Create an accepted response (202) with no caching and a location header.
javax.ws.rs.core.Response.ResponseBuilder	created(URI location) Create a created response with no-cache headers.
javax.ws.rs.core.Response.ResponseBuilder	created(URI location, Object data) Create a created response with no-cache headers and with the given response data.
static Date	date(String stamp) Parse the formated date-time stamp.
protected String	datetime(long millis) Auxiliary to format milliseconds timestamps into a standard format.
javax.ws.rs.core.Response.ResponseBuilder	deleted() Create a deleted response with no-cache headers.
static String	format(Date date) Get the formated date-time stamp for the given date.
static String	format(long number) Get the formated number.
org.apache.commons.configuration.XMLConfiguration	getData(String root, String request) Get the XML configuration created from the specified request data and rooted at the specified element.
static String	getUserName(Principal principal) Get the user name for the specified principal.
Integer	id(String sid) Get the integer variant of the specified string ID.
int	integer(String string) Get the integer variant of the specified string number.
javax.ws.rs.WebApplicationException	notFound() Get an exception for signaling that a resource was not found.
javax.ws.rs.core.Response.ResponseBuilder	ok() Create a no-content (204) response with no caching.
javax.ws.rs.core.Response.ResponseBuilder	ok(Object data) Create a pre-populated response with no-cache headers and with the given response data.
protected javax.ws.rs.core.Response.ResponseBuilder	redirect(String path) Returns redirect response to the specified path.
static String	ref(javax.ws.rs.core.UriInfo ui, Class<?> resourceClass, String uid) Construct a reference to the resource of the specified type and with the given unique id.
static String	safeCamelCase(String prefix, Enum<?> e) Protect against values that are null when creating camel case representations of enumerations.
static String	safeToString(Object o) Protects against values that are null.
javax.ws.rs.WebApplicationException	serverError() Get an exception for signaling that a server error has occurred.
javax.ws.rs.WebApplicationException	serviceUnavailableError() Get an exception for signaling that a requested service is unavailable.
static void	setDefaultUserName(String userName) Sets the default user name, which will be used when no current principal context exists.
String	sid(Integer id) Get the string variant of the specified integer ID.
static WebUtils.Tag	tag(String name, Object content) Create a new XML tag with the specified name and content.
static WebUtils.Tag	tag(javax.ws.rs.core.UriInfo ui, Class<?> resourceClass, String name, Identified entity) Produces an XML tag with embedded uid and ref elements.
static WebUtils.Tag	tag(javax.ws.rs.core.UriInfo ui, Class<?> resourceClass, String name, String uid) Produces an XML tag with embedded uid and ref elements.
String	uid(String urlPath) Extracts entity uid from the specified URL path.
String	uid(URL url) Extracts entity uid from the specified URL.
URL	url(String path) Generate a URL using the supplied path.
protected String	validate(String uid) Validate the specified uid to make sure it's not null or empty.
protected void	validate(String uid, String uidr) Validate the specified uids against each other.
protected <T> T	validate(T entity) Validates that the specified entity is not null.
javax.ws.rs.WebApplicationException	warn(String message, Object arg1, Object arg2, javax.ws.rs.core.Response.Status status) Deprecated.
javax.ws.rs.WebApplicationException	warn(String message, Object arg, javax.ws.rs.core.Response.Status status) Deprecated.

Methods inherited from class java.lang.Object

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

Field Detail

UID

public static final String UID

See Also:

Constant Field Values

REF

public static final String REF

See Also:

Constant Field Values

NAME

public static final String NAME

See Also:

Constant Field Values

DATETIME_FORMAT

protected static final String DATETIME_FORMAT

See Also:

Constant Field Values

DATE_FORMAT

protected static final String DATE_FORMAT

See Also:

Constant Field Values

NO_CACHE

protected static final javax.ws.rs.core.CacheControl NO_CACHE

Cache control descriptor to force no-caching.

log

protected final org.slf4j.Logger log

security

@Context
protected javax.ws.rs.core.SecurityContext security

uriInfo

@Context
protected javax.ws.rs.core.UriInfo uriInfo

DEFAULT_USER

protected static final String DEFAULT_USER

See Also:

Constant Field Values

Constructor Detail

BaseResource

protected BaseResource(org.slf4j.Logger log)

Create a resource capable of logging to the specified logger.

Parameters:

log - logger

Method Detail

setDefaultUserName

public static void setDefaultUserName(String userName)

Sets the default user name, which will be used when no current principal context exists. This is provided for unit test support and will have no effect in production context as the application operates in secured context, where default user is never used.

Parameters:

userName - new default user name

getUserName

public static String getUserName(Principal principal)

Get the user name for the specified principal. If the principal is null, it is assumed we're running in dev or test mode.

Parameters:

principal - user or group principal context

Returns:

user name

validate

protected <T> T validate(T entity)

Validates that the specified entity is not null. If it is, it throws a not-found web application exception.

Type Parameters:

T - type of entity being validated

Parameters:

entity - entity to be validated

Returns:

the specified entity

Throws:

javax.ws.rs.WebApplicationException - with 404 code if entity is null

tag

public static WebUtils.Tag tag(String name,
               Object content)

Create a new XML tag with the specified name and content.

Parameters:

name - tag name

content - tag content

Returns:

newly created tag

tag

public static WebUtils.Tag tag(javax.ws.rs.core.UriInfo ui,
               Class<?> resourceClass,
               String name,
               Identified entity)

Produces an XML tag with embedded uid and ref elements.

Parameters:

ui - request context

resourceClass - resource class

name - name of the tag

entity - entity from which to extract uid

Returns:

XML tag

tag

public static WebUtils.Tag tag(javax.ws.rs.core.UriInfo ui,
               Class<?> resourceClass,
               String name,
               String uid)

Produces an XML tag with embedded uid and ref elements.

Parameters:

ui - request context

resourceClass - resource class

name - name of the tag

uid - unique id of the resource

Returns:

XML tag

validate

protected void validate(String uid,
            String uidr)

Validate the specified uids against each other.

Parameters:

uid - uid from the resource ref

uidr - uid from the request body

Throws:

javax.ws.rs.WebApplicationException - with bad request code if the given uids do not match

validate

protected String validate(String uid)

Validate the specified uid to make sure it's not null or empty.

Parameters:

uid - uid from the resource ref

Returns:

the uid

Throws:

javax.ws.rs.WebApplicationException - with bad request code if the id is null or empty

url

public URL url(String path)

Generate a URL using the supplied path. Propagate errors to the client via HTTP 500 response.

Parameters:

path - url string path

Returns:

url descriptor constructed from the path

Throws:

javax.ws.rs.WebApplicationException - with internal error the given path does not form a valid URL

uid

public String uid(URL url)

Extracts entity uid from the specified URL.

Parameters:

url - url from which the uid is to be extracted

Returns:

unique id of an entity whose URL is given

uid

public String uid(String urlPath)

Extracts entity uid from the specified URL path.

Parameters:

urlPath - url path from which the uid is to be extracted

Returns:

unique id of an entity whose URL is given

Throws:

javax.ws.rs.WebApplicationException - with internal error if UID could not be extracted from the given URL path

ref

public static String ref(javax.ws.rs.core.UriInfo ui,
         Class<?> resourceClass,
         String uid)

Construct a reference to the resource of the specified type and with the given unique id.

Parameters:

ui - base uri info

resourceClass - resource type

uid - unique id of the entity

Returns:

URL path of the resource

getData

public org.apache.commons.configuration.XMLConfiguration getData(String root,
                                                        String request)

Get the XML configuration created from the specified request data and rooted at the specified element.

Parameters:

root - root element name

request - XML-encoded request data

Returns:

XML configuration object

Throws:

javax.ws.rs.WebApplicationException - with bad request if data could not be extracted

ok

public javax.ws.rs.core.Response.ResponseBuilder ok()

Create a no-content (204) response with no caching.

Returns:

response builder

accepted

public javax.ws.rs.core.Response.ResponseBuilder accepted()

Create an accepted response (202) with no caching.

Returns:

response builder

accepted

public javax.ws.rs.core.Response.ResponseBuilder accepted(URI location)

Create an accepted response (202) with no caching and a location header.

Parameters:

location - URI location

Returns:

response builder

ok

public javax.ws.rs.core.Response.ResponseBuilder ok(Object data)

Create a pre-populated response with no-cache headers and with the given response data.

Parameters:

data - response data

Returns:

response builder

created

public javax.ws.rs.core.Response.ResponseBuilder created(URI location)

Create a created response with no-cache headers.

Parameters:

location - URI location

Returns:

response builder

created

public javax.ws.rs.core.Response.ResponseBuilder created(URI location,
                                                Object data)

Create a created response with no-cache headers and with the given response data.

Parameters:

location - URI location

data - created data

Returns:

response builder

deleted

public javax.ws.rs.core.Response.ResponseBuilder deleted()

Create a deleted response with no-cache headers.

Returns:

response builder

redirect

protected javax.ws.rs.core.Response.ResponseBuilder redirect(String path)

Returns redirect response to the specified path.

The provided path string will be normalized (see URI.normalize()) prior to the creation of the redirect response. It is recommended that an absolute path be provided if path normalization is expected.

Parameters:

path - path to which redirect should lead

Returns:

redirect response builder

Throws:

javax.ws.rs.WebApplicationException - with internal error if redirect failed

notFound

public javax.ws.rs.WebApplicationException notFound()

Get an exception for signaling that a resource was not found.

Returns:

newly created web-application exception with NOT_FOUND status

serverError

public javax.ws.rs.WebApplicationException serverError()

Get an exception for signaling that a server error has occurred.

Returns:

newly created web-application exception with INTERNAL_SERVER_ERROR status

serviceUnavailableError

public javax.ws.rs.WebApplicationException serviceUnavailableError()

Get an exception for signaling that a requested service is unavailable.

Returns:

newly created web-application exception with SERVICE_UNAVAILABLE status

warn

@Deprecated
public javax.ws.rs.WebApplicationException warn(String message,
                                                  Object arg,
                                                  javax.ws.rs.core.Response.Status status)

Deprecated.

Log a warning with the specified message and return a new web-app exception for the specified response status.

Parameters:

message - message to log as a warning

arg - object to use in lieu of a place-holder in the message

status - response status

Returns:

ready-to-throw web application exception

warn

@Deprecated
public javax.ws.rs.WebApplicationException warn(String message,
                                                  Object arg1,
                                                  Object arg2,
                                                  javax.ws.rs.core.Response.Status status)

Deprecated.

Log a warning with the specified message and return a new web-app exception for the specified response status.

Parameters:

message - message to log as a warning

arg1 - object to use in lieu of the first placeholder in the message

arg2 - object to use in lieu of the second placeholder in the message

status - response status

Returns:

ready-to-throw web application exception

sid

public String sid(Integer id)

Get the string variant of the specified integer ID.

Parameters:

id - entity ID

Returns:

ID as a string

id

public Integer id(String sid)

Get the integer variant of the specified string ID.

Parameters:

sid - entity ID

Returns:

ID as an integer

Throws:

javax.ws.rs.WebApplicationException - with bad request if the given id is not a number

format

public static String format(long number)

Get the formated number.

Parameters:

number - number to be formatted

Returns:

standard number format

format

public static String format(Date date)

Get the formated date-time stamp for the given date.

Parameters:

date - date to be formatted

Returns:

standard date-time format

date

public static Date date(String stamp)

Parse the formated date-time stamp.

Parameters:

stamp - date-time stamp string

Returns:

parsed date

datetime

protected String datetime(long millis)

Auxiliary to format milliseconds timestamps into a standard format.

Parameters:

millis - time since epoch

Returns:

standard date/time stamp - not localized

integer

public int integer(String string)

Get the integer variant of the specified string number.

Parameters:

string - string containing number

Returns:

parsed integer

Throws:

javax.ws.rs.WebApplicationException - with bad request if the given string does not parse into a number

safeToString

public static String safeToString(Object o)

Protects against values that are null. Returns either an empty string (if null) or Object.toString().

Parameters:

o - the object to be formatted (may be null)

Returns:

string representation

safeCamelCase

public static String safeCamelCase(String prefix,
                   Enum<?> e)

Protect against values that are null when creating camel case representations of enumerations.

Parameters:

prefix - camel prefix

e - enum value

Returns:

prefixed camel-case of the enum