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.