Module org.refcodes.rest
Package org.refcodes.rest

Class AbstractRestfulServer

java.lang.Object
org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>
org.refcodes.rest.AbstractRestfulServer
All Implemented Interfaces:
org.refcodes.mixin.Disposable, org.refcodes.observer.Observable<RestEndpoint>, org.refcodes.observer.Observers<RestEndpoint,RestfulServer>, RestfulServer, org.refcodes.web.BaseLocatorAccessor, org.refcodes.web.BaseLocatorAccessor.BaseLocatorBuilder<RestfulServer>, org.refcodes.web.BaseLocatorAccessor.BaseLocatorMutator, org.refcodes.web.BaseLocatorAccessor.BaseLocatorProperty, org.refcodes.web.MediaTypeFactoryLookup, org.refcodes.web.MediaTypeFactoryLookup.MutableMediaTypeFactoryLookup, org.refcodes.web.RealmAccessor, org.refcodes.web.RealmAccessor.RealmBuilder<RestfulServer>, org.refcodes.web.RealmAccessor.RealmMutator, org.refcodes.web.RealmAccessor.RealmProperty
Direct Known Subclasses:
HttpRestServer, LoopbackRestServer
public abstract class AbstractRestfulServer extends org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest> implements RestfulServer
Implementation of the base functionality of the RestfulServer interface omitting the HTTP handling part being the foundation for various RestfulServer implementations such as HttpRestServer or LoopbackRestServer. The AbstractRestfulServer is preconfigured with the following MediaTypeFactory instances:
  • JsonMediaTypeFactory
  • XmlMediaTypeFactory
  • TextMediaTypeFactory
  • FormMediaTypeFactory
In your sub-classes, overwrite the method initMedaTypeFactories(), therein calling addMediaTypeFactory(MediaTypeFactory) to add (by also invoking super's initMedaTypeFactories()) or to set your own (without invoking super's initMedaTypeFactories()) MediaTypeFactory instances. Set the system property SystemProperty.LOG_DEBUG to true (set when invoking the JRA by passing the argument -Dlog.debug=true to the java executable) to log additional erroneous situations e.g. related to content types and accept types alongside marshaling and unmarshaling.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.refcodes.web.BaseLocatorAccessor

    org.refcodes.web.BaseLocatorAccessor.BaseLocatorBuilder<B extends org.refcodes.web.BaseLocatorAccessor.BaseLocatorBuilder<B>>, org.refcodes.web.BaseLocatorAccessor.BaseLocatorMutator, org.refcodes.web.BaseLocatorAccessor.BaseLocatorProperty

    Nested classes/interfaces inherited from interface org.refcodes.web.MediaTypeFactoryLookup

    org.refcodes.web.MediaTypeFactoryLookup.MutableMediaTypeFactoryLookup

    Nested classes/interfaces inherited from interface org.refcodes.web.RealmAccessor

    org.refcodes.web.RealmAccessor.RealmBuilder<B extends org.refcodes.web.RealmAccessor.RealmBuilder<B>>, org.refcodes.web.RealmAccessor.RealmMutator, org.refcodes.web.RealmAccessor.RealmProperty

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    _isVerbose
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractRestfulServer()
    Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.
    AbstractRestfulServer(boolean isVerbose)
    Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.
    AbstractRestfulServer(ExecutorService aExecutorService)
    Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.
    AbstractRestfulServer(ExecutorService aExecutorService, boolean isVerbose)
    Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    addMediaTypeFactory(org.refcodes.web.MediaTypeFactory aMediaTypeFactory)
    void
    dispose()
    protected boolean
    fireEvent(org.refcodes.web.HttpRequest aEvent, RestEndpoint aObserver, org.refcodes.controlflow.ExecutionStrategy aExecutionStrategy)
    String
    getBaseLocator()
    org.refcodes.web.MediaType[]
    getFactoryMediaTypes()
    String
    getRealm()
    protected void
    initMedaTypeFactories()
    Adds the default MediaTypeFactory instances.
    boolean
    isObserversActive()
    Iterator<RestEndpoint>
    observers()
    protected void
    onHttpRequest(InetSocketAddress aLocalAddress, InetSocketAddress aRemoteAddress, org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, org.refcodes.web.RequestHeaderFields aRequestHeaderFields, InputStream aHttpInputStream, org.refcodes.web.HttpServerResponse aHttpServerResponse)
    Extensions of this class disect an incoming request and pass it to this method for doing the actual invocation of the registered RestEndpoint instances.
    protected void
    postIntercept(org.refcodes.web.HttpServerRequest aRequest, org.refcodes.web.HttpServerResponse aResponse)
    Invoked to post-process a HttpServerRequest alongside a HttpServerResponse.
    protected void
    preIntercept(org.refcodes.web.HttpServerRequest aRequest, org.refcodes.web.HttpServerResponse aResponse)
    Invoked to pre-process a HttpServerRequest alongside a HttpServerResponse.
    void
    setBaseLocator(String aBaseLocator)
    void
    setObserversActive(boolean isActive)
    void
    setRealm(String aRealm)
    boolean
    subscribeObserver(RestEndpoint aObserver)
    org.refcodes.web.MediaTypeFactory
    toMediaTypeFactory(org.refcodes.web.MediaType aMediaType)
    protected org.refcodes.web.ContentType
    toNegotiatedContenType(org.refcodes.web.RequestHeaderFields aRequestHeaderFields)
    Determines the best fitting respone's ContentType.
    protected byte[]
    toResponseBody(Object aResponse, org.refcodes.web.RequestHeaderFields aRequestHeaderFields, org.refcodes.web.ResponseHeaderFields aResponseHeaderFields)
    Creates a String MediaType encoded as of the HeaderField.CONTENT_TYPE from the response header or if not set as of the HeaderField.ACCEPT from the request header or if not set as of the HeaderField.CONTENT_TYPE from the request header.
    boolean
    unsubscribeObserver(RestEndpoint aObserver)

    Methods inherited from class org.refcodes.observer.AbstractObservable

    clear, doHandleEventListenerException, fireEvent, getThreadPriority, hasObserver, isEmpty, setThreadPriority, size

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.refcodes.web.BaseLocatorAccessor.BaseLocatorProperty

    letBaseLocator

    Methods inherited from interface org.refcodes.web.MediaTypeFactoryLookup

    hasMediaTypeFactory

    Methods inherited from interface org.refcodes.observer.Observable

    hasObserver

    Methods inherited from interface org.refcodes.observer.Observers

    disableObservers, enableObservers

    Methods inherited from interface org.refcodes.web.RealmAccessor.RealmProperty

    letRealm

    Methods inherited from interface org.refcodes.rest.RestfulServer

    onDelete, onDelete, onGet, onGet, onPost, onPost, onPut, onPut, onRequest, onRequest, onRequest, onRequest, onRequest, withBaseLocator, withDisableObservers, withEnableObservers, withObserversActive, withRealm

  • Field Details

    • _isVerbose

      protected boolean _isVerbose

  • Constructor Details

    • AbstractRestfulServer

      public AbstractRestfulServer()
      Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.

    • AbstractRestfulServer

      public AbstractRestfulServer(boolean isVerbose)
      Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.
      Parameters:
      isVerbose - When true, any unknown content- and accept-types are logged.

    • AbstractRestfulServer

      public AbstractRestfulServer(ExecutorService aExecutorService)
      Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.
      Parameters:
      aExecutorService - An executor service to be used when creating Threads.

    • AbstractRestfulServer

      public AbstractRestfulServer(ExecutorService aExecutorService, boolean isVerbose)
      Constructs a AbstractRestfulServer preconfigured with MediaTypeFactory instances for JSON and REST.
      Parameters:
      aExecutorService - An executor service to be used when creating Threads.
      isVerbose - When true, any unknown content- and accept-types are logged.

  • Method Details

    • initMedaTypeFactories

      protected void initMedaTypeFactories()
      Adds the default MediaTypeFactory instances. Can be overridden.

    • setObserversActive

      public void setObserversActive(boolean isActive)
      Specified by:
      setObserversActive in interface org.refcodes.observer.Observers<RestEndpoint,RestfulServer>
      Overrides:
      setObserversActive in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

    • isObserversActive

      public boolean isObserversActive()
      Specified by:
      isObserversActive in interface org.refcodes.observer.Observers<RestEndpoint,RestfulServer>
      Overrides:
      isObserversActive in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

    • observers

      public Iterator<RestEndpoint> observers()
      Specified by:
      observers in interface org.refcodes.observer.Observers<RestEndpoint,RestfulServer>
      Overrides:
      observers in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

    • getRealm

      public String getRealm()
      Specified by:
      getRealm in interface org.refcodes.web.RealmAccessor

    • setRealm

      public void setRealm(String aRealm)
      Specified by:
      setRealm in interface org.refcodes.web.RealmAccessor.RealmMutator

    • getBaseLocator

      public String getBaseLocator()
      Specified by:
      getBaseLocator in interface org.refcodes.web.BaseLocatorAccessor

    • setBaseLocator

      public void setBaseLocator(String aBaseLocator)
      Specified by:
      setBaseLocator in interface org.refcodes.web.BaseLocatorAccessor.BaseLocatorMutator

    • subscribeObserver

      public boolean subscribeObserver(RestEndpoint aObserver)
      Specified by:
      subscribeObserver in interface org.refcodes.observer.Observable<RestEndpoint>
      Overrides:
      subscribeObserver in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

    • unsubscribeObserver

      public boolean unsubscribeObserver(RestEndpoint aObserver)
      Specified by:
      unsubscribeObserver in interface org.refcodes.observer.Observable<RestEndpoint>
      Overrides:
      unsubscribeObserver in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

    • addMediaTypeFactory

      public boolean addMediaTypeFactory(org.refcodes.web.MediaTypeFactory aMediaTypeFactory)
      Specified by:
      addMediaTypeFactory in interface org.refcodes.web.MediaTypeFactoryLookup.MutableMediaTypeFactoryLookup

    • toMediaTypeFactory

      public org.refcodes.web.MediaTypeFactory toMediaTypeFactory(org.refcodes.web.MediaType aMediaType)
      Specified by:
      toMediaTypeFactory in interface org.refcodes.web.MediaTypeFactoryLookup

    • getFactoryMediaTypes

      public org.refcodes.web.MediaType[] getFactoryMediaTypes()
      Specified by:
      getFactoryMediaTypes in interface org.refcodes.web.MediaTypeFactoryLookup

    • dispose

      public void dispose()
      Specified by:
      dispose in interface org.refcodes.mixin.Disposable
      Overrides:
      dispose in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

    • onHttpRequest

      protected void onHttpRequest(InetSocketAddress aLocalAddress, InetSocketAddress aRemoteAddress, org.refcodes.web.HttpMethod aHttpMethod, org.refcodes.web.Url aUrl, org.refcodes.web.RequestHeaderFields aRequestHeaderFields, InputStream aHttpInputStream, org.refcodes.web.HttpServerResponse aHttpServerResponse) throws org.refcodes.web.HttpStatusException
      Extensions of this class disect an incoming request and pass it to this method for doing the actual invocation of the registered RestEndpoint instances. An extension might call this method from inside an event (request) handler.
      Parameters:
      aLocalAddress - The host and port of your REST service.
      aRemoteAddress - The host and port for the caller.
      aHttpMethod - The HttpMethod of the request.
      aUrl - The Url from which to take the URL specific data.
      aRequestHeaderFields - The Header-Fields (HeaderFields) belonging to the request.
      aHttpInputStream - The body passed by the request.
      aHttpServerResponse - A HttpServerResponse instance to be used by the extension to produce an according HTTP-Response.
      Throws:
      org.refcodes.web.HttpStatusException - thrown in case of an RestEndpoint responsible for the given request encountered a problem or none RestEndpoint felt responsible to produce a HttpServerResponse.

    • toNegotiatedContenType

      protected org.refcodes.web.ContentType toNegotiatedContenType(org.refcodes.web.RequestHeaderFields aRequestHeaderFields)
      Determines the best fitting respone's ContentType. The default Content-Type-Negotiation implementation of this method makes use of the RequestHeaderFields and matches them against the supported MediaType types ( retrieved via getFactoryMediaTypes()). May be overwritten to enforce another Content-Type-Negotiation strategy.
      Parameters:
      aRequestHeaderFields - The request's HeaderField instance to use when determining the best fitting respone's ContentType.
      Returns:
      The best fitting (as of the implemented Content-Type-Negotiation strategy) Content-Type to be used for the response.

    • toResponseBody

      protected byte[] toResponseBody(Object aResponse, org.refcodes.web.RequestHeaderFields aRequestHeaderFields, org.refcodes.web.ResponseHeaderFields aResponseHeaderFields) throws org.refcodes.exception.MarshalException, org.refcodes.web.UnsupportedMediaTypeException
      Creates a String MediaType encoded as of the HeaderField.CONTENT_TYPE from the response header or if not set as of the HeaderField.ACCEPT from the request header or if not set as of the HeaderField.CONTENT_TYPE from the request header.
      Parameters:
      aResponse - The response which to encode as of the detected MediaTypes.
      aRequestHeaderFields - The Header-Fields from the request.
      aResponseHeaderFields - The Header-Fields from the response.
      Returns:
      An accordingly encoded response as byte array.
      Throws:
      org.refcodes.exception.MarshalException - thrown when marshaling / serializing an object failed.
      org.refcodes.web.UnsupportedMediaTypeException - thrown in case none of the identified media types is supported, e.g. no required MediaTypeFactory has been registered as of addMediaTypeFactory(MediaTypeFactory).

    • fireEvent

      protected boolean fireEvent(org.refcodes.web.HttpRequest aEvent, RestEndpoint aObserver, org.refcodes.controlflow.ExecutionStrategy aExecutionStrategy) throws org.refcodes.exception.VetoException
      Specified by:
      fireEvent in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>
      Throws:
      org.refcodes.exception.VetoException

    • preIntercept

      protected void preIntercept(org.refcodes.web.HttpServerRequest aRequest, org.refcodes.web.HttpServerResponse aResponse)
      Invoked to pre-process a HttpServerRequest alongside a HttpServerResponse.
      Parameters:
      aRequest - The HttpServerRequest to pre-process.
      aResponse - The HttpServerResponse to post-process.

    • postIntercept

      protected void postIntercept(org.refcodes.web.HttpServerRequest aRequest, org.refcodes.web.HttpServerResponse aResponse)
      Invoked to post-process a HttpServerRequest alongside a HttpServerResponse.
      Parameters:
      aRequest - The HttpServerRequest to post-process.
      aResponse - The HttpServerResponse to post-process.