org.restlet.ext.wadl
Class WadlApplication

java.lang.Object
  extended by org.restlet.Restlet
      extended by org.restlet.Application
          extended by org.restlet.ext.wadl.WadlApplication
All Implemented Interfaces:
Uniform

public class WadlApplication
extends Application

WADL enabled application. This Application subclass can describe itself in WADL by introspecting its content, supporting the standard WADL/XML format or a WADL/HTML one based on a built-in XSLT transformation. You can obtain this representation with an OPTIONS request addressed exactly to the application URI (e.g. "http://host:port/path/to/application"). By default, the returned representation gleans the list of all attached ServerResource classes and calls Restlet.getName() to get the title and Restlet.getDescription() the textual content of the WADL document generated. This default behavior can be customized by overriding the getApplicationInfo(Request, Response) method.

In case you want to customize the XSLT stylesheet, you can override the createWadlRepresentation(ApplicationInfo) method and return an instance of an WadlRepresentation subclass overriding the WadlRepresentation.getHtmlRepresentation() method.

In addition, this class can create an instance and configure it with an user-provided WADL/XML document. In this case, it creates a root Router and for each resource found in the WADL document, it tries to attach a ServerResource class to the router using its WADL path. For this, it looks up the qualified name of the ServerResource subclass using the WADL's "id" attribute of the "resource" elements. This is the only Restlet specific convention on the original WADL document.

To attach an application configured in this way to an existing component, you can call the attachToComponent(Component) or the attachToHost(VirtualHost) methods. In this case, it uses the "base" attribute of the WADL "resources" element as the URI attachment path to the virtual host.

For the HTML description to work properly, you will certainly have to update your classpath with a recent version of Apache Xalan XSLT engine (version 2.7.1 has been successfully tested). This is due to the XSLT stylesheet bundled which relies on EXSLT features.

Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
Jerome Louvel

Constructor Summary
WadlApplication()
          Creates an application that can automatically introspect and expose itself as with a WADL description upon reception of an OPTIONS request on the "*" target URI.
WadlApplication(Context context)
          Creates an application that can automatically introspect and expose itself as with a WADL description upon reception of an OPTIONS request on the "*" target URI.
WadlApplication(Context context, Representation wadl)
          Creates an application described using a WADL document.
WadlApplication(Representation wadl)
          Creates an application described using a WADL document.
 
Method Summary
 VirtualHost attachToComponent(Component component)
          Attaches the application to the given component if the application has a WADL base reference.
 void attachToHost(VirtualHost host)
          Attaches the application to the given host using the WADL base reference.
protected  boolean canDescribe(String remainingPart, Request request, Response response)
          Indicates if the application and all its resources can be described using WADL.
protected  Finder createFinder(Router router, String uriPattern, ResourceInfo resourceInfo)
          Creates a finder for the given resource info.
protected  Representation createHtmlRepresentation(ApplicationInfo applicationInfo)
          Creates a new HTML representation for a given ApplicationInfo instance describing an application.
protected  Representation createWadlRepresentation(ApplicationInfo applicationInfo)
          Creates a new WADL representation for a given ApplicationInfo instance describing an application.
protected  ApplicationInfo getApplicationInfo(Request request, Response response)
          Returns a WADL description of the current application.
 Reference getBaseRef()
          Returns the WADL base reference.
protected  Variant getPreferredWadlVariant(Request request)
          Returns the preferred WADL variant according to the client preferences specified in the request.
 Router getRouter()
          Returns the router where the ServerResource classes created from the WADL description document are attached.
protected  List<Variant> getWadlVariants()
          Returns the available WADL variants.
 void handle(Request request, Response response)
          Handles the requests normally in all cases then handles the special case of the OPTIONS requests that exactly target the application.
 boolean isAutoDescribing()
          Indicates if the application should be automatically described via WADL when an OPTIONS request handles a "*" target URI.
 void setAutoDescribing(boolean autoDescribed)
          Indicates if the application should be automatically described via WADL when an OPTIONS request handles a "*" target URI.
 void setBaseRef(Reference baseRef)
          Sets the WADL base reference.
protected  Representation wadlRepresent(Request request, Response response)
          Represents the resource as a WADL description.
protected  Representation wadlRepresent(Variant variant, Request request, Response response)
          Represents the resource as a WADL description for the given variant.
 
Methods inherited from class org.restlet.Application
createInboundRoot, createOutboundRoot, getConnectorService, getConnegService, getConverterService, getCurrent, getDecoderService, getEncoderService, getInboundRoot, getMetadataService, getOutboundRoot, getRangeService, getRole, getRoles, getServices, getStatusService, getTaskService, getTunnelService, setClientRoot, setConnectorService, setConnegService, setContext, setConverterService, setCurrent, setDecoderService, setEncoderService, setInboundRoot, setInboundRoot, setMetadataService, setOutboundRoot, setOutboundRoot, setRangeService, setRoles, setStatusService, setTaskService, setTunnelService, start, stop
 
Methods inherited from class org.restlet.Restlet
createFinder, finalize, getApplication, getAuthor, getContext, getDescription, getFinderClass, getLogger, getName, getOwner, handle, handle, handle, isStarted, isStopped, setAuthor, setDescription, setFinderClass, setName, setOwner
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WadlApplication

public WadlApplication()
Creates an application that can automatically introspect and expose itself as with a WADL description upon reception of an OPTIONS request on the "*" target URI.


WadlApplication

public WadlApplication(Context context)
Creates an application that can automatically introspect and expose itself as with a WADL description upon reception of an OPTIONS request on the "*" target URI.

Parameters:
context - The context to use based on parent component context. This context should be created using the Context.createChildContext() method to ensure a proper isolation with the other applications.

WadlApplication

public WadlApplication(Context context,
                       Representation wadl)
Creates an application described using a WADL document. Creates a router where Resource classes are attached and set it as the root Restlet. By default the application is not automatically described. If you want to, you can call setAutoDescribing(boolean).

Parameters:
context - The context to use based on parent component context. This context should be created using the Context.createChildContext() method to ensure a proper isolation with the other applications.
wadl - The WADL description document.

WadlApplication

public WadlApplication(Representation wadl)
Creates an application described using a WADL document. Creates a router where Resource classes are attached and set it as the root Restlet. By default the application is not automatically described. If you want to, you can call setAutoDescribing(boolean).

Parameters:
wadl - The WADL description document.
Method Detail

attachToComponent

public VirtualHost attachToComponent(Component component)
Attaches the application to the given component if the application has a WADL base reference. The application will be attached to an existing virtual host if possible, otherwise a new one will be created.

Parameters:
component - The parent component to update.
Returns:
The parent virtual host.

attachToHost

public void attachToHost(VirtualHost host)
Attaches the application to the given host using the WADL base reference.

Parameters:
host - The virtual host to attach to.

canDescribe

protected boolean canDescribe(String remainingPart,
                              Request request,
                              Response response)
Indicates if the application and all its resources can be described using WADL.

Parameters:
remainingPart - The URI remaining part.
request - The request to handle.
response - The response to update.

createFinder

protected Finder createFinder(Router router,
                              String uriPattern,
                              ResourceInfo resourceInfo)
                       throws ClassNotFoundException
Creates a finder for the given resource info. By default, it looks up for an "id" attribute containing a fully qualified class name.

Parameters:
router - The parent router.
resourceInfo - The WADL resource descriptor.
Returns:
The created finder.
Throws:
ClassNotFoundException

createHtmlRepresentation

protected Representation createHtmlRepresentation(ApplicationInfo applicationInfo)
Creates a new HTML representation for a given ApplicationInfo instance describing an application.

Parameters:
applicationInfo - The application description.
Returns:
The created WadlRepresentation.

createWadlRepresentation

protected Representation createWadlRepresentation(ApplicationInfo applicationInfo)
Creates a new WADL representation for a given ApplicationInfo instance describing an application.

Parameters:
applicationInfo - The application description.
Returns:
The created WadlRepresentation.

getApplicationInfo

protected ApplicationInfo getApplicationInfo(Request request,
                                             Response response)
Returns a WADL description of the current application. By default, this method discovers all the resources attached to this application. It can be overridden to add documentation, list of representations, etc.

Parameters:
request - The current request.
response - The current response.
Returns:
An application description.

getBaseRef

public Reference getBaseRef()
Returns the WADL base reference.

Returns:
The WADL base reference.

getPreferredWadlVariant

protected Variant getPreferredWadlVariant(Request request)
Returns the preferred WADL variant according to the client preferences specified in the request.

Parameters:
request - The request including client preferences.
Returns:
The preferred WADL variant.

getRouter

public Router getRouter()
Returns the router where the ServerResource classes created from the WADL description document are attached.

Returns:
The root router.

getWadlVariants

protected List<Variant> getWadlVariants()
Returns the available WADL variants.

Returns:
The available WADL variants.

handle

public void handle(Request request,
                   Response response)
Handles the requests normally in all cases then handles the special case of the OPTIONS requests that exactly target the application. In this case, the application is automatically introspected and described as a WADL representation based on the result of the getApplicationInfo(Request, Response) method.
The automatic introspection happens only if the request hasn't already been successfully handled. That is to say, it lets users provide their own handling of OPTIONS requests.

Specified by:
handle in interface Uniform
Overrides:
handle in class Application
Parameters:
request - The request to handle.
response - The response to update.

isAutoDescribing

public boolean isAutoDescribing()
Indicates if the application should be automatically described via WADL when an OPTIONS request handles a "*" target URI.

Returns:
True if the application should be automatically described via WADL.

setAutoDescribing

public void setAutoDescribing(boolean autoDescribed)
Indicates if the application should be automatically described via WADL when an OPTIONS request handles a "*" target URI.

Parameters:
autoDescribed - True if the application should be automatically described via WADL.

setBaseRef

public void setBaseRef(Reference baseRef)
Sets the WADL base reference.

Parameters:
baseRef - The WADL base reference.

wadlRepresent

protected Representation wadlRepresent(Request request,
                                       Response response)
Represents the resource as a WADL description.

Parameters:
request - The current request.
response - The current response.
Returns:
The WADL description.

wadlRepresent

protected Representation wadlRepresent(Variant variant,
                                       Request request,
                                       Response response)
Represents the resource as a WADL description for the given variant.

Parameters:
variant - The WADL variant.
request - The current request.
response - The current response.
Returns:
The WADL description.


Copyright © 2005-2013 Restlet.