Class AbstractRestServer

java.lang.Object

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

org.refcodes.rest.AbstractRestServer

All Implemented Interfaces:

Disposable, Observable<RestEndpoint>, Observers<RestEndpoint, RestServer>, RestServer, BaseLocatorAccessor, BaseLocatorAccessor.BaseLocatorBuilder<RestServer>, BaseLocatorAccessor.BaseLocatorMutator, BaseLocatorAccessor.BaseLocatorProperty, MediaTypeFactoryLookup, MediaTypeFactoryLookup.MutableMediaTypeFactoryLookup, RealmAccessor, RealmAccessor.RealmBuilder<RestServer>, RealmAccessor.RealmMutator, RealmAccessor.RealmProperty

Direct Known Subclasses:

JdkHttpRestServer, LoopbackRestServer

public abstract class AbstractRestServer
extends AbstractObservable<RestEndpoint, 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 JdkHttpRestServer or LoopbackRestServer. The AbstractRestServer 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 BaseLocatorAccessor

BaseLocatorAccessor.BaseLocatorBuilder<B>, BaseLocatorAccessor.BaseLocatorMutator, BaseLocatorAccessor.BaseLocatorProperty

Nested classes/interfaces inherited from interface MediaTypeFactoryLookup

MediaTypeFactoryLookup.MutableMediaTypeFactoryLookup

Nested classes/interfaces inherited from interface RealmAccessor

RealmAccessor.RealmBuilder<B>, RealmAccessor.RealmMutator, RealmAccessor.RealmProperty

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	_isVerbose

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
boolean	addMediaTypeFactory(MediaTypeFactory aMediaTypeFactory)
void	dispose()
protected boolean	fireEvent(HttpRequest aEvent, RestEndpoint aObserver, ExecutionStrategy aExecutionStrategy)
String	getBaseLocator()
MediaType[]	getFactoryMediaTypes()
String	getRealm()
protected void	initMedaTypeFactories()	Adds the default MediaTypeFactory instances.
boolean	isObserversActive()
Iterator<RestEndpoint>	observers()
protected void	onHttpRequest(InetSocketAddress aLocalAddress, InetSocketAddress aRemoteAddress, HttpMethod aHttpMethod, Url aUrl, RequestHeaderFields aRequestHeaderFields, InputStream aHttpInputStream, 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(HttpServerRequest aRequest, HttpServerResponse aResponse)	Invoked to post-process a HttpServerRequest alongside a HttpServerResponse.
protected void	preIntercept(HttpServerRequest aRequest, 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)
MediaTypeFactory	toMediaTypeFactory(MediaType aMediaType)
protected ContentType	toNegotiatedContenType(RequestHeaderFields aRequestHeaderFields)	Determines the best fitting respone's ContentType.
protected byte[]	toResponseBody(Object aResponse, RequestHeaderFields aRequestHeaderFields, 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 AbstractObservable

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

Methods inherited from class Object

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

Methods inherited from interface BaseLocatorAccessor.BaseLocatorProperty

letBaseLocator

Methods inherited from interface MediaTypeFactoryLookup

hasMediaTypeFactory

Methods inherited from interface Observable

hasObserver

Methods inherited from interface Observers

disableObservers, enableObservers

Methods inherited from interface RealmAccessor.RealmProperty

letRealm

Methods inherited from interface RestServer

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

AbstractRestServer

public AbstractRestServer()

Constructs a AbstractRestServer preconfigured with MediaTypeFactory instances for JSON and REST.

AbstractRestServer

public AbstractRestServer(boolean isVerbose)

Constructs a AbstractRestServer preconfigured with MediaTypeFactory instances for JSON and REST.

Parameters:

isVerbose - When true, any unknown content- and accept-types are logged.

AbstractRestServer

public AbstractRestServer(ExecutorService aExecutorService)

Constructs a AbstractRestServer preconfigured with MediaTypeFactory instances for JSON and REST.

Parameters:

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

AbstractRestServer

public AbstractRestServer(ExecutorService aExecutorService,
 boolean isVerbose)

Constructs a AbstractRestServer 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 Observers<RestEndpoint, RestServer>

Overrides:

setObserversActive in class AbstractObservable<RestEndpoint, HttpRequest>

isObserversActive

public boolean isObserversActive()

Specified by:

isObserversActive in interface Observers<RestEndpoint, RestServer>

Overrides:

isObserversActive in class AbstractObservable<RestEndpoint, HttpRequest>

observers

public Iterator<RestEndpoint> observers()

Specified by:

observers in interface Observers<RestEndpoint, RestServer>

Overrides:

observers in class AbstractObservable<RestEndpoint, HttpRequest>

getRealm

public String getRealm()

Specified by:

getRealm in interface RealmAccessor

setRealm

public void setRealm(String aRealm)

Specified by:

setRealm in interface RealmAccessor.RealmMutator

getBaseLocator

public String getBaseLocator()

Specified by:

getBaseLocator in interface BaseLocatorAccessor

setBaseLocator

public void setBaseLocator(String aBaseLocator)

Specified by:

setBaseLocator in interface BaseLocatorAccessor.BaseLocatorMutator

subscribeObserver

public boolean subscribeObserver(RestEndpoint aObserver)

Specified by:

subscribeObserver in interface Observable<RestEndpoint>

Overrides:

subscribeObserver in class AbstractObservable<RestEndpoint, HttpRequest>

unsubscribeObserver

public boolean unsubscribeObserver(RestEndpoint aObserver)

Specified by:

unsubscribeObserver in interface Observable<RestEndpoint>

Overrides:

unsubscribeObserver in class AbstractObservable<RestEndpoint, HttpRequest>

addMediaTypeFactory

public boolean addMediaTypeFactory(MediaTypeFactory aMediaTypeFactory)

Specified by:

addMediaTypeFactory in interface MediaTypeFactoryLookup.MutableMediaTypeFactoryLookup

toMediaTypeFactory

public MediaTypeFactory toMediaTypeFactory(MediaType aMediaType)

Specified by:

toMediaTypeFactory in interface MediaTypeFactoryLookup

getFactoryMediaTypes

public MediaType[] getFactoryMediaTypes()

Specified by:

getFactoryMediaTypes in interface MediaTypeFactoryLookup

dispose

public void dispose()

Specified by:

dispose in interface Disposable

Overrides:

dispose in class AbstractObservable<RestEndpoint, HttpRequest>

onHttpRequest

protected void onHttpRequest(InetSocketAddress aLocalAddress,
 InetSocketAddress aRemoteAddress,
 HttpMethod aHttpMethod,
 Url aUrl,
 RequestHeaderFields aRequestHeaderFields,
 InputStream aHttpInputStream,
 HttpServerResponse aHttpServerResponse)
                      throws 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:

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 ContentType toNegotiatedContenType(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,
 RequestHeaderFields aRequestHeaderFields,
 ResponseHeaderFields aResponseHeaderFields)
                         throws MarshalException,
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:

MarshalException - thrown when marshaling / serializing an object failed.

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(HttpRequest aEvent,
 RestEndpoint aObserver,
 ExecutionStrategy aExecutionStrategy)
                     throws VetoException

Specified by:

fireEvent in class AbstractObservable<RestEndpoint, HttpRequest>

Throws:

VetoException

preIntercept

protected void preIntercept(HttpServerRequest aRequest,
 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(HttpServerRequest aRequest,
 HttpServerResponse aResponse)

Invoked to post-process a HttpServerRequest alongside a HttpServerResponse.

Parameters:

aRequest - The HttpServerRequest to post-process.

aResponse - The HttpServerResponse to post-process.