Module org.refcodes.rest

Package org.refcodes.rest

Class AbstractRestServer

java.lang.Object

org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

org.refcodes.rest.AbstractRestServer

All Implemented Interfaces:

org.refcodes.observer.Observable<RestServer>, org.refcodes.observer.Observers<RestEndpoint,RestServer>, HttpExceptionHandlerAccessor, HttpExceptionHandlerAccessor.HttpExceptionHandlerBuilder<RestServer>, HttpExceptionHandlerAccessor.HttpExceptionHandlerMutator, HttpExceptionHandlerAccessor.HttpExceptionHandlerProperty, HttpExceptionHandlingAccessor, HttpExceptionHandlingAccessor.HttpExceptionHandlingBuilder<RestServer>, HttpExceptionHandlingAccessor.HttpExceptionHandlingMutator, HttpExceptionHandlingAccessor.HttpExceptionHandlingProperty, RestServer, org.refcodes.runtime.RequestCorrelation<RestServer>, org.refcodes.runtime.SessionCorrelation<RestServer>, org.refcodes.web.BaseLocatorAccessor, org.refcodes.web.BaseLocatorAccessor.BaseLocatorBuilder<RestServer>, 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<RestServer>, org.refcodes.web.RealmAccessor.RealmMutator, org.refcodes.web.RealmAccessor.RealmProperty

Direct Known Subclasses:

HttpRestServerImpl, LoopbackRestServerImpl

public abstract class AbstractRestServer
extends org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>
implements RestServer

Implementation of the base functionality of the RestServer interface omitting the HTTP handling part being the foundation for various RestServer implementations such as HttpRestServerImpl or LoopbackRestServerImpl. The AbstractRestServer is pre-configured 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.

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.mixin.Disposable

org.refcodes.mixin.Disposable.Disposedable

Nested classes/interfaces inherited from interface org.refcodes.rest.HttpExceptionHandlerAccessor

HttpExceptionHandlerAccessor.HttpExceptionHandlerBuilder<B extends HttpExceptionHandlerAccessor.HttpExceptionHandlerBuilder<B>>, HttpExceptionHandlerAccessor.HttpExceptionHandlerMutator, HttpExceptionHandlerAccessor.HttpExceptionHandlerProperty

Nested classes/interfaces inherited from interface org.refcodes.rest.HttpExceptionHandlingAccessor

HttpExceptionHandlingAccessor.HttpExceptionHandlingBuilder<B extends HttpExceptionHandlingAccessor.HttpExceptionHandlingBuilder<B>>, HttpExceptionHandlingAccessor.HttpExceptionHandlingMutator, HttpExceptionHandlingAccessor.HttpExceptionHandlingProperty

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	_hasRequestCorrelation
protected boolean	_hasSessionCorrelation
protected HttpExceptionHandler	_httpExceptionHandler
protected HttpExceptionHandling	_httpExceptionHandling

Fields inherited from interface org.refcodes.mixin.Loggable

RUNTIME_LOGGER_CLASS, RUNTIME_LOGGER_FACTORY_CLASS, RUNTIME_LOGGER_FACTORY_METHOD

Constructor Summary

Constructors

Constructor	Description
AbstractRestServer()	Constructs a AbstractRestServer pre-configured with MediaTypeFactory instances for JSON and REST.
AbstractRestServer(ExecutorService aExecutorService)	CConstructs a AbstractRestServer pre-configured with MediaTypeFactory instances for JSON and REST.

Method Summary

Modifier and Type	Method	Description
boolean	addMediaTypeFactory(org.refcodes.web.MediaTypeFactory aMediaTypeFactory)
void	dispose()
protected void	doRequestCorrelation(org.refcodes.web.RequestHeaderFields aRequestHeaderFields, org.refcodes.web.HttpServerResponse aServerResponse)	Do request correlation.
protected void	doSessionCorrelation(org.refcodes.web.RequestHeaderFields aRequestHeaderFields, org.refcodes.web.HttpServerResponse aServerResponse)	Do session correlation.
protected boolean	fireEvent(org.refcodes.web.HttpRequest aEvent, RestEndpoint aObserver, org.refcodes.controlflow.ExecutionStrategy aExecutionStrategy)
String	getBaseLocator()
org.refcodes.web.MediaType[]	getFactoryMediaTypes()
HttpExceptionHandler	getHttpExceptionHandler()	Retrieves the HttpExceptionHandler from the HttpExceptionHandler property.
HttpExceptionHandling	getHttpExceptionHandling()	Retrieves the HttpExceptionHandling from the HttpExceptionHandling property.
String	getRealm()
boolean	hasRequestCorrelation()
boolean	hasSessionCorrelation()
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.
void	setBaseLocator(String aBaseLocator)
void	setHttpExceptionHandler(HttpExceptionHandler aHttpErrorHandler)	Sets the HttpExceptionHandler for the HttpExceptionHandler property.
void	setHttpExceptionHandling(HttpExceptionHandling aHttpErrorHandling)	Sets the HttpExceptionHandling for the HttpExceptionHandling property.
void	setObserversActive(boolean isActive)
void	setRealm(String aRealm)
void	setRequestCorrelation(boolean hasRequestCorrelation)
void	setSessionCorrelation(boolean hasSessionCorrelation)
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, hasObserverSubscription, isEmpty, setThreadPriority, size

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

letBaseLocator

Methods inherited from interface org.refcodes.rest.HttpExceptionHandlerAccessor.HttpExceptionHandlerBuilder

withHttpExceptionHandler, withOnHttpException

Methods inherited from interface org.refcodes.rest.HttpExceptionHandlerAccessor.HttpExceptionHandlerMutator

onHttpException

Methods inherited from interface org.refcodes.rest.HttpExceptionHandlerAccessor.HttpExceptionHandlerProperty

letHttpExceptionHandler

Methods inherited from interface org.refcodes.rest.HttpExceptionHandlingAccessor.HttpExceptionHandlingBuilder

withHttpExceptionHandling

Methods inherited from interface org.refcodes.rest.HttpExceptionHandlingAccessor.HttpExceptionHandlingProperty

letHttpExceptionHandling

Methods inherited from interface org.refcodes.mixin.Loggable

alert, alert, critical, critical, debug, error, info, notice, panic, trace, warn, warn

Methods inherited from interface org.refcodes.web.MediaTypeFactoryLookup

hasMediaTypeFactory

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.refcodes.observer.Observable

hasObserverSubscription

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.runtime.RequestCorrelation

disableRequestCorrelation, enableRequestCorrelation

Methods inherited from interface org.refcodes.rest.RestServer

onDelete, onDelete, onGet, onGet, onPost, onPost, onPut, onPut, onRequest, onRequest, onRequest, onRequest, onRequest, withBaseLocator, withDisableObservers, withDisableRequestCorrelation, withDisableSessionCorrelation, withEnableObservers, withEnableRequestCorrelation, withEnableSessionCorrelation, withObserversActive, withRealm, withRequestCorrelation, withSessionCorrelation

Methods inherited from interface org.refcodes.runtime.SessionCorrelation

disableSessionCorrelation, enableSessionCorrelation

Field Detail

_hasRequestCorrelation

protected boolean _hasRequestCorrelation

_hasSessionCorrelation

protected boolean _hasSessionCorrelation

_httpExceptionHandling

protected HttpExceptionHandling _httpExceptionHandling

_httpExceptionHandler

protected HttpExceptionHandler _httpExceptionHandler

Constructor Detail

AbstractRestServer

public AbstractRestServer()

Constructs a AbstractRestServer pre-configured with MediaTypeFactory instances for JSON and REST.

AbstractRestServer

public AbstractRestServer(ExecutorService aExecutorService)

CConstructs a AbstractRestServer pre-configured with MediaTypeFactory instances for JSON and REST.

Parameters:

aExecutorService - An executor service to be used when creating Threads.

Method Detail

initMedaTypeFactories

protected void initMedaTypeFactories()

Adds the default MediaTypeFactory instances. Can be overridden.

getHttpExceptionHandler

public HttpExceptionHandler getHttpExceptionHandler()

Retrieves the HttpExceptionHandler from the HttpExceptionHandler property.

Specified by:

getHttpExceptionHandler in interface HttpExceptionHandlerAccessor

Returns:

The HttpExceptionHandler stored by the HttpExceptionHandler property.

setHttpExceptionHandler

public void setHttpExceptionHandler(HttpExceptionHandler aHttpErrorHandler)

Sets the HttpExceptionHandler for the HttpExceptionHandler property.

Specified by:

setHttpExceptionHandler in interface HttpExceptionHandlerAccessor.HttpExceptionHandlerMutator

Parameters:

aHttpErrorHandler - The HttpExceptionHandler to be stored by the HttpExceptionHandler property.

getHttpExceptionHandling

public HttpExceptionHandling getHttpExceptionHandling()

Retrieves the HttpExceptionHandling from the HttpExceptionHandling property.

Specified by:

getHttpExceptionHandling in interface HttpExceptionHandlingAccessor

Returns:

The HttpExceptionHandling stored by the HttpExceptionHandling property.

setHttpExceptionHandling

public void setHttpExceptionHandling(HttpExceptionHandling aHttpErrorHandling)

Sets the HttpExceptionHandling for the HttpExceptionHandling property.

Specified by:

setHttpExceptionHandling in interface HttpExceptionHandlingAccessor.HttpExceptionHandlingMutator

Parameters:

aHttpErrorHandling - The HttpExceptionHandling to be stored by the HttpExceptionHandling property.

setObserversActive

public void setObserversActive(boolean isActive)

Specified by:

setObserversActive in interface org.refcodes.observer.Observers<RestEndpoint,RestServer>

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,RestServer>

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,RestServer>

Overrides:

observers in class org.refcodes.observer.AbstractObservable<RestEndpoint,org.refcodes.web.HttpRequest>

setRequestCorrelation

public void setRequestCorrelation(boolean hasRequestCorrelation)

Specified by:

setRequestCorrelation in interface org.refcodes.runtime.RequestCorrelation<RestServer>

hasRequestCorrelation

public boolean hasRequestCorrelation()

Specified by:

hasRequestCorrelation in interface org.refcodes.runtime.RequestCorrelation<RestServer>

setSessionCorrelation

public void setSessionCorrelation(boolean hasSessionCorrelation)

Specified by:

setSessionCorrelation in interface org.refcodes.runtime.SessionCorrelation<RestServer>

hasSessionCorrelation

public boolean hasSessionCorrelation()

Specified by:

hasSessionCorrelation in interface org.refcodes.runtime.SessionCorrelation<RestServer>

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

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

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()

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

doRequestCorrelation

protected void doRequestCorrelation(org.refcodes.web.RequestHeaderFields aRequestHeaderFields,
                                    org.refcodes.web.HttpServerResponse aServerResponse)

Do request correlation.

Parameters:

aRequestHeaderFields - the request Header-Fields

aServerResponse - the server response

doSessionCorrelation

protected void doSessionCorrelation(org.refcodes.web.RequestHeaderFields aRequestHeaderFields,
                                    org.refcodes.web.HttpServerResponse aServerResponse)

Do session correlation.

Parameters:

aRequestHeaderFields - the request Header-Fields

aServerResponse - the server response