org.restlet.util
Class Engine

java.lang.Object
  org.restlet.util.Engine

public abstract class Engine
extends Object

Facade to the engine implementating the Restlet API. Note that this is an SPI class that is not intended for public usage.

Author:

Jerome Louvel

Field Summary

static String	MAJOR_NUMBER Major version number.
static String	MINOR_NUMBER Minor version number.
static String	RELEASE_NUMBER Release number.
static String	VERSION Complete version.

Constructor Summary

Engine()

Method Summary

abstract int	authenticate(Request request, Guard guard) Indicates if the call is properly authenticated.
abstract void	challenge(Response response, boolean stale, Guard guard) Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.
abstract void	copyResponseHeaders(Iterable<Parameter> headers, Response response) Copies the given header parameters into the given Response.
abstract void	copyResponseHeaders(Response response, Series<Parameter> headers) Copies the headers of the given Response into the given Series.
abstract Resource	createDirectoryResource(Directory handler, Request request, Response response) Creates a directory resource.
abstract Helper<Application>	createHelper(Application application) Creates a new helper for a given component.
abstract Helper<Client>	createHelper(Client client, String helperClass) Creates a new helper for a given client connector.
abstract Helper<Component>	createHelper(Component component) Creates a new helper for a given component.
abstract Helper<Server>	createHelper(Server server, String helperClass) Creates a new helper for a given server connector.
abstract void	fireContextChanged(Restlet restlet, Context context) Indicates that a Restlet's context has changed.
abstract String	formatCookie(Cookie cookie) Formats the given Cookie to a String
abstract String	formatCookieSetting(CookieSetting cookieSetting) Formats the given CookieSetting to a String
abstract String	formatDimensions(Collection<Dimension> dimensions) Formats the given Set of Dimensions to a String for the HTTP Vary header.
abstract String	formatUserAgent(List<Product> products) Formats the given List of Products to a String.
static ClassLoader	getClassLoader() Returns the best class loader, first the engine class loader if available using getUserClassLoader(), otherwise the current thread context class loader, or finally the classloader of the current class.
static Engine	getInstance() Returns the registered Restlet engine.
abstract Variant	getPreferredVariant(ClientInfo client, List<Variant> variants, Language defaultLanguage) Returns the best variant representation for a given resource according the the client preferences. A default language is provided in case the variants don't match the client preferences.
static int	hashCode(Object... objects) Computes the hash code of a set of objects.
static Class<?>	loadClass(String className) Returns the class object for the given name using the engine class loader fist, then the current thread context class loader, or the classloader of the current class.
abstract void	parse(Form form, Representation representation) Parses a representation into a form.
abstract void	parse(Form form, String parametersString, CharacterSet characterSet, boolean decode, char separator) Parses a parameters string to parse into a given form.
abstract MediaType	parseContentType(String contentType) Parses the given Content Type.
abstract Cookie	parseCookie(String cookie) Parses the given String to a Cookie
abstract CookieSetting	parseCookieSetting(String cookieSetting) Parses the given String to a CookieSetting
abstract List<Product>	parseUserAgent(String userAgent) Parses the given user agent String to a list of Product instances.
static void	setInstance(Engine engine) Sets the registered Restlet engine.
static void	setUserClassLoader(ClassLoader newClassLoader) Sets the user class loader that should used in priority.
abstract String	toBase64(byte[] target) Converts the given bytes array into a Base64 String.
abstract String	toMd5(String target) Returns the MD5 digest of the target string.

Methods inherited from class java.lang.Object

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

Field Detail

MAJOR_NUMBER

public static final String MAJOR_NUMBER

Major version number.

See Also:

Constant Field Values

MINOR_NUMBER

public static final String MINOR_NUMBER

Minor version number.

See Also:

Constant Field Values

RELEASE_NUMBER

public static final String RELEASE_NUMBER

Release number.

See Also:

Constant Field Values

VERSION

public static final String VERSION

Complete version.

See Also:

Constant Field Values

Constructor Detail

Engine

public Engine()

Method Detail

getClassLoader

public static ClassLoader getClassLoader()

Returns the best class loader, first the engine class loader if available using getUserClassLoader(), otherwise the current thread context class loader, or finally the classloader of the current class.

Returns:

The best class loader.

getInstance

public static Engine getInstance()

Returns the registered Restlet engine.

Returns:

The registered Restlet engine.

hashCode

public static int hashCode(Object... objects)

Computes the hash code of a set of objects. Follows the algorithm specified in List.hasCode().

Parameters:

objects - the objects to compute the hashCode

Returns:

The hash code of a set of objects.

loadClass

public static Class<?> loadClass(String className)
                          throws ClassNotFoundException

Returns the class object for the given name using the engine class loader fist, then the current thread context class loader, or the classloader of the current class.

Parameters:

className - The class name to lookup.

Returns:

The class object or null if the class was not found.

Throws:

ClassNotFoundException

setInstance

public static void setInstance(Engine engine)

Sets the registered Restlet engine.

Parameters:

engine - The registered Restlet engine.

setUserClassLoader

public static void setUserClassLoader(ClassLoader newClassLoader)

Sets the user class loader that should used in priority.

Parameters:

newClassLoader - The new user class loader to use.

authenticate

public abstract int authenticate(Request request,
                                 Guard guard)

Indicates if the call is properly authenticated. By default, this delegates credential checking to checkSecret().

Parameters:

request - The request to authenticate.

guard - The associated guard to callback.

Returns:

-1 if the given credentials were invalid, 0 if no credentials were found and 1 otherwise.

See Also:

Guard.checkSecret(Request, String, char[])

challenge

public abstract void challenge(Response response,
                               boolean stale,
                               Guard guard)

Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.

Parameters:

response - The response to update.

stale - Indicates if the new challenge is due to a stale response.

guard - The associated guard to callback.

copyResponseHeaders

public abstract void copyResponseHeaders(Iterable<Parameter> headers,
                                         Response response)

Copies the given header parameters into the given Response.

Parameters:

headers - The headers to copy.

response - The response to update. Must contain a Representation to copy the representation headers in it.

copyResponseHeaders

public abstract void copyResponseHeaders(Response response,
                                         Series<Parameter> headers)

Copies the headers of the given Response into the given Series.

Parameters:

response - The response to update. Should contain a Representation to copy the representation headers from it.

headers - The Series to copy the headers in.

createDirectoryResource

public abstract Resource createDirectoryResource(Directory handler,
                                                 Request request,
                                                 Response response)
                                          throws IOException

Creates a directory resource.

Parameters:

handler - The parent directory handler.

request - The request to handle.

response - The response to return.

Returns:

A new directory resource.

Throws:

IOException

createHelper

public abstract Helper<Application> createHelper(Application application)

Creates a new helper for a given component.

Parameters:

application - The application to help.

Returns:

The new helper.

createHelper

public abstract Helper<Client> createHelper(Client client,
                                            String helperClass)

Creates a new helper for a given client connector.

Parameters:

client - The client to help.

helperClass - Optional helper class name.

Returns:

The new helper.

createHelper

public abstract Helper<Component> createHelper(Component component)

Creates a new helper for a given component.

Parameters:

component - The component to help.

Returns:

The new helper.

createHelper

public abstract Helper<Server> createHelper(Server server,
                                            String helperClass)

Creates a new helper for a given server connector.

Parameters:

server - The server to help.

helperClass - Optional helper class name.

Returns:

The new helper.

fireContextChanged

public abstract void fireContextChanged(Restlet restlet,
                                        Context context)

Indicates that a Restlet's context has changed.

Parameters:

restlet - The Restlet with a changed context.

context - The new context.

formatCookie

public abstract String formatCookie(Cookie cookie)
                             throws IllegalArgumentException

Formats the given Cookie to a String

Parameters:

cookie -

Returns:

the Cookie as String

Throws:

IllegalArgumentException - Thrown if the Cookie contains illegal values

formatCookieSetting

public abstract String formatCookieSetting(CookieSetting cookieSetting)
                                    throws IllegalArgumentException

Formats the given CookieSetting to a String

Parameters:

cookieSetting -

Returns:

the CookieSetting as String

Throws:

IllegalArgumentException - Thrown if the CookieSetting contains illegal values

formatDimensions

public abstract String formatDimensions(Collection<Dimension> dimensions)

Formats the given Set of Dimensions to a String for the HTTP Vary header.

Parameters:

dimensions - the dimensions to format.

Returns:

the Vary header or null, if dimensions is null or empty.

formatUserAgent

public abstract String formatUserAgent(List<Product> products)
                                throws IllegalArgumentException

Formats the given List of Products to a String.

Parameters:

products - The list of products to format.

Returns:

the List of Products as String.

Throws:

IllegalArgumentException - Thrown if the List of Products contains illegal values

getPreferredVariant

public abstract Variant getPreferredVariant(ClientInfo client,
                                            List<Variant> variants,
                                            Language defaultLanguage)

Returns the best variant representation for a given resource according the the client preferences.
A default language is provided in case the variants don't match the client preferences.

Parameters:

client - The client preferences.

variants - The list of variants to compare.

defaultLanguage - The default language.

Returns:

The preferred variant.

See Also:

Apache content negotiation algorithm< /a>

parse

public abstract void parse(Form form,
                           Representation representation)

Parses a representation into a form.

Parameters:

form - The target form.

representation - The representation to parse.

parse

public abstract void parse(Form form,
                           String parametersString,
                           CharacterSet characterSet,
                           boolean decode,
                           char separator)

Parses a parameters string to parse into a given form.

Parameters:

form - The target form.

parametersString - The parameters string to parse.

characterSet - The supported character encoding.

decode - Indicates if the parameters should be decoded using the given character set.

separator - The separator character to append between parameters.

parseContentType

public abstract MediaType parseContentType(String contentType)
                                    throws IllegalArgumentException

Parses the given Content Type.

Parameters:

contentType - the Content Type as String

Returns:

the ContentType as MediaType; charset etc. are parameters.

Throws:

IllegalArgumentException - if the String can not be parsed.

parseCookie

public abstract Cookie parseCookie(String cookie)
                            throws IllegalArgumentException

Parses the given String to a Cookie

Parameters:

cookie -

Returns:

the Cookie parsed from the String

Throws:

IllegalArgumentException - Thrown if the String can not be parsed as Cookie.

parseCookieSetting

public abstract CookieSetting parseCookieSetting(String cookieSetting)
                                          throws IllegalArgumentException

Parses the given String to a CookieSetting

Parameters:

cookieSetting -

Returns:

the CookieSetting parsed from the String

Throws:

IllegalArgumentException - Thrown if the String can not be parsed as CookieSetting.

parseUserAgent

public abstract List<Product> parseUserAgent(String userAgent)
                                      throws IllegalArgumentException

Parses the given user agent String to a list of Product instances.

Parameters:

userAgent -

Returns:

the List of Product objects parsed from the String

Throws:

IllegalArgumentException - Thrown if the String can not be parsed as a list of Product instances.

toBase64

public abstract String toBase64(byte[] target)

Converts the given bytes array into a Base64 String.

Parameters:

target - The bytes array to encode.

Returns:

The Base64 String.

toMd5

public abstract String toMd5(String target)

Returns the MD5 digest of the target string. Target is decoded to bytes using the US-ASCII charset. The returned hexidecimal String always contains 32 lowercase alphanumeric characters. For example, if target is "HelloWorld", this method returns "68e109f0f40ca72a15e05cc22786f8e6".

Parameters:

target - The string to encode.

Returns:

The MD5 digest of the target string.