com.h3c.util.rs

## Class BaseResource

- java.lang.Object
- - com.h3c.util.rs.BaseResource

- Direct Known Subclasses:
    AgentAwareResource, FileSystemResource

      public abstract class BaseResource
      extends Object

  Base REST resource implementation.

- - ### 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

Copyright © 2014. All Rights Reserved.