org.restlet.engine
Class Engine

java.lang.Object
  extended by org.restlet.engine.Engine

public class Engine
extends Object

Engine supporting the Restlet API. The engine acts as a registry of various Helper types: AuthenticatorHelper , ClientHelper, ConverterHelper and ServerHelper classes.

Note that by default the JULI logging mechanism is used but it is possible to replace it by providing an alternate LoggerFacade implementation. For this, just pass a system property named "org.restlet.engine.loggerFacadeClass" with the qualified class name as a value.

Author:
Jerome Louvel

Field Summary
static String DESCRIPTOR
           
static String DESCRIPTOR_AUTHENTICATOR
           
static String DESCRIPTOR_AUTHENTICATOR_PATH
           
static String DESCRIPTOR_CLIENT
           
static String DESCRIPTOR_CLIENT_PATH
           
static String DESCRIPTOR_CONVERTER
           
static String DESCRIPTOR_CONVERTER_PATH
           
static String DESCRIPTOR_PROTOCOL
           
static String DESCRIPTOR_PROTOCOL_PATH
           
static String DESCRIPTOR_SERVER
           
static String DESCRIPTOR_SERVER_PATH
           
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.
static String VERSION_HEADER
          Complete version header.
 
Constructor Summary
Engine()
          Constructor that will automatically attempt to discover connectors.
Engine(boolean discoverHelpers)
          Constructor.
 
Method Summary
static void clear()
          Clears the current Restlet Engine altogether.
static void clearThreadLocalVariables()
          Clears the thread local variables set by the Restlet API and engine.
static void configureLog()
          Updates the global log configuration of the JVM programmatically.
protected  ClassLoader createClassLoader()
          Creates a new class loader.
 ConnectorHelper<Client> createHelper(Client client, String helperClass)
          Creates a new helper for a given client connector.
 ConnectorHelper<Server> createHelper(Server server, String helperClass)
          Creates a new helper for a given server connector.
static Thread createThreadWithLocalVariables(Runnable runnable, String name)
          Creates a new standalone thread with local Restlet thread variable properly set.
 ConverterHelper findHelper()
          Finds the converter helper supporting the given conversion.
 AuthenticatorHelper findHelper(ChallengeScheme challengeScheme, boolean clientSide, boolean serverSide)
          Finds the authenticator helper supporting the given scheme.
static Logger getAnonymousLogger()
          Returns an anonymous logger.
 ClassLoader getClassLoader()
          Returns the class loader.
static Engine getInstance()
          Returns the registered Restlet engine.
static Class<? extends Formatter> getLogFormatter()
          Returns the general log formatter.
static Logger getLogger(Class<?> clazz)
          Returns a logger based on the class name of the given object.
static Logger getLogger(Class<?> clazz, String defaultLoggerName)
          Returns a logger based on the class name of the given object.
static Logger getLogger(Object object, String defaultLoggerName)
          Returns a logger based on the class name of the given object.
static Logger getLogger(String loggerName)
          Returns a logger based on the given logger name.
 LoggerFacade getLoggerFacade()
          Returns the logger facade to use.
static Level getLogLevel()
          Returns the general log level.
 List<AuthenticatorHelper> getRegisteredAuthenticators()
          Returns the list of available authentication helpers.
 List<ConnectorHelper<Client>> getRegisteredClients()
          Returns the list of available client connectors.
 List<ConverterHelper> getRegisteredConverters()
          Returns the list of available converters.
 List<ProtocolHelper> getRegisteredProtocols()
          Returns the list of available protocol connectors.
 List<ConnectorHelper<Server>> getRegisteredServers()
          Returns the list of available server connectors.
static URL getResource(String name)
          Returns the classloader resource for a given name/path.
static Level getRestletLogLevel()
          Returns the Restlet log level.
 ClassLoader getUserClassLoader()
          Returns the class loader specified by the user and that should be used in priority.
static Class<?> loadClass(String className)
          Returns the class object for the given name using the engine classloader.
static Engine register()
          Registers a new Restlet Engine.
static Engine register(boolean discoverPlugins)
          Registers a new Restlet Engine.
 void registerDefaultAuthentications()
          Registers the default authentication helpers.
 void registerDefaultConnectors()
          Registers the default client and server connectors.
 void registerDefaultConverters()
          Registers the default converters.
 void registerDefaultProtocols()
          Registers the default protocols.
 void registerHelper(ClassLoader classLoader, String provider, List helpers, Class constructorClass)
          Registers a helper.
 void registerHelpers(ClassLoader classLoader, URL configUrl, List<?> helpers, Class<?> constructorClass)
          Registers a helper.
 void registerHelpers(String descriptorPath, List<?> helpers, Class<?> constructorClass)
          Registers a list of helpers.
 void registerUrlFactory()
          Registers a factory that is used by the URL class to create the URLConnection instances when the URL.openConnection() or URL.openStream() methods are invoked.
 void setClassLoader(ClassLoader newClassLoader)
          Sets the engine class loader.
static void setInstance(Engine engine)
          Deprecated. Use the register() and register(boolean) methods instead.
static void setLogFormatter(Class<? extends Formatter> logFormatter)
          Sets the general log formatter.
 void setLoggerFacade(LoggerFacade loggerFacade)
          Sets the logger facade to use.
static void setLogLevel(Level logLevel)
          Sets the general log level.
 void setRegisteredAuthenticators(List<AuthenticatorHelper> registeredAuthenticators)
          Sets the list of available authentication helpers.
 void setRegisteredClients(List<ConnectorHelper<Client>> registeredClients)
          Sets the list of available client helpers.
 void setRegisteredConverters(List<ConverterHelper> registeredConverters)
          Sets the list of available converter helpers.
 void setRegisteredProtocols(List<ProtocolHelper> registeredProtocols)
          Sets the list of available protocol helpers.
 void setRegisteredServers(List<ConnectorHelper<Server>> registeredServers)
          Sets the list of available server helpers.
static void setRestletLogLevel(Level restletLogLevel)
          Sets the Restlet log level.
 void setUserClassLoader(ClassLoader newClassLoader)
          Sets the user class loader that should used in priority.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DESCRIPTOR

public static final String DESCRIPTOR
See Also:
Constant Field Values

DESCRIPTOR_AUTHENTICATOR

public static final String DESCRIPTOR_AUTHENTICATOR
See Also:
Constant Field Values

DESCRIPTOR_AUTHENTICATOR_PATH

public static final String DESCRIPTOR_AUTHENTICATOR_PATH
See Also:
Constant Field Values

DESCRIPTOR_CLIENT

public static final String DESCRIPTOR_CLIENT
See Also:
Constant Field Values

DESCRIPTOR_CLIENT_PATH

public static final String DESCRIPTOR_CLIENT_PATH
See Also:
Constant Field Values

DESCRIPTOR_CONVERTER

public static final String DESCRIPTOR_CONVERTER
See Also:
Constant Field Values

DESCRIPTOR_CONVERTER_PATH

public static final String DESCRIPTOR_CONVERTER_PATH
See Also:
Constant Field Values

DESCRIPTOR_PROTOCOL

public static final String DESCRIPTOR_PROTOCOL
See Also:
Constant Field Values

DESCRIPTOR_PROTOCOL_PATH

public static final String DESCRIPTOR_PROTOCOL_PATH
See Also:
Constant Field Values

DESCRIPTOR_SERVER

public static final String DESCRIPTOR_SERVER
See Also:
Constant Field Values

DESCRIPTOR_SERVER_PATH

public static final String DESCRIPTOR_SERVER_PATH
See Also:
Constant Field Values

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

VERSION_HEADER

public static final String VERSION_HEADER
Complete version header.

See Also:
Constant Field Values
Constructor Detail

Engine

public Engine()
Constructor that will automatically attempt to discover connectors.


Engine

public Engine(boolean discoverHelpers)
Constructor.

Parameters:
discoverHelpers - True if helpers should be automatically discovered.
Method Detail

clear

public static void clear()
Clears the current Restlet Engine altogether.


createThreadWithLocalVariables

public static Thread createThreadWithLocalVariables(Runnable runnable,
                                                    String name)
Creates a new standalone thread with local Restlet thread variable properly set.

Parameters:
runnable - The runnable task to execute.
name - The thread name.
Returns:
The thread with proper variables ready to run the given runnable task.

clearThreadLocalVariables

public static void clearThreadLocalVariables()
Clears the thread local variables set by the Restlet API and engine.


configureLog

public static void configureLog()
Updates the global log configuration of the JVM programmatically.


getAnonymousLogger

public static Logger getAnonymousLogger()
Returns an anonymous logger. By default it calls getLogger(String) with a "" name.

Returns:
The logger.

getInstance

public static Engine getInstance()
Returns the registered Restlet engine.

Returns:
The registered Restlet engine.

getLogFormatter

public static Class<? extends Formatter> getLogFormatter()
Returns the general log formatter.

Returns:
The general log formatter.

getLogger

public static Logger getLogger(Class<?> clazz)
Returns a logger based on the class name of the given object.

Parameters:
clazz - The parent class.
Returns:
The logger.

getLogger

public static Logger getLogger(Class<?> clazz,
                               String defaultLoggerName)
Returns a logger based on the class name of the given object.

Parameters:
clazz - The parent class.
defaultLoggerName - The default logger name to use if no one can be inferred from the class.
Returns:
The logger.

getLogger

public static Logger getLogger(Object object,
                               String defaultLoggerName)
Returns a logger based on the class name of the given object.

Parameters:
object - The parent object.
defaultLoggerName - The default logger name to use if no one can be inferred from the object class.
Returns:
The logger.

getLogger

public static Logger getLogger(String loggerName)
Returns a logger based on the given logger name.

Parameters:
loggerName - The logger name.
Returns:
The logger.

getLogLevel

public static Level getLogLevel()
Returns the general log level.

Returns:
The general log level.

getResource

public static URL getResource(String name)
Returns the classloader resource for a given name/path.

Parameters:
name - The name/path to lookup.
Returns:
The resource URL.

getRestletLogLevel

public static Level getRestletLogLevel()
Returns the Restlet log level. For loggers with a name starting with "org.restlet".

Returns:
The Restlet log level.

loadClass

public static Class<?> loadClass(String className)
                          throws ClassNotFoundException
Returns the class object for the given name using the engine classloader.

Parameters:
className - The class name to lookup.
Returns:
The class object or null if the class was not found.
Throws:
ClassNotFoundException
See Also:
getClassLoader()

register

public static Engine register()
Registers a new Restlet Engine.

Returns:
The registered engine.

register

public static Engine register(boolean discoverPlugins)
Registers a new Restlet Engine.

Parameters:
discoverPlugins - True if plug-ins should be automatically discovered.
Returns:
The registered engine.

setInstance

@Deprecated
public static void setInstance(Engine engine)
Deprecated. Use the register() and register(boolean) methods instead.

Sets the registered Restlet engine.

Parameters:
engine - The registered Restlet engine.

setLogFormatter

public static void setLogFormatter(Class<? extends Formatter> logFormatter)
Sets the general log formatter.

Parameters:
logFormatter - The general log formatter.

setLogLevel

public static void setLogLevel(Level logLevel)
Sets the general log level. Modifies the global JVM's LogManager.

Parameters:
logLevel - The general log level.

setRestletLogLevel

public static void setRestletLogLevel(Level restletLogLevel)
Sets the Restlet log level. For loggers with a name starting with "org.restlet".

Parameters:
restletLogLevel - The Restlet log level.

createClassLoader

protected ClassLoader createClassLoader()
Creates a new class loader. By default, it returns an instance of EngineClassLoader.

Returns:
A new class loader.

createHelper

public ConnectorHelper<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 ConnectorHelper<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.

findHelper

public ConverterHelper findHelper()
Finds the converter helper supporting the given conversion.

Returns:
The converter helper or null.

findHelper

public AuthenticatorHelper findHelper(ChallengeScheme challengeScheme,
                                      boolean clientSide,
                                      boolean serverSide)
Finds the authenticator helper supporting the given scheme.

Parameters:
challengeScheme - The challenge scheme to match.
clientSide - Indicates if client side support is required.
serverSide - Indicates if server side support is required.
Returns:
The authenticator helper or null.

getClassLoader

public ClassLoader getClassLoader()
Returns the class loader. It uses the delegation model with the Engine class's class loader as a parent. If this parent doesn't find a class or resource, it then tries the user class loader (via getUserClassLoader() and finally the Thread.getContextClassLoader().

Returns:
The engine class loader.
See Also:
EngineClassLoader

getLoggerFacade

public LoggerFacade getLoggerFacade()
Returns the logger facade to use.

Returns:
The logger facade to use.

getRegisteredAuthenticators

public List<AuthenticatorHelper> getRegisteredAuthenticators()
Returns the list of available authentication helpers.

Returns:
The list of available authentication helpers.

getRegisteredClients

public List<ConnectorHelper<Client>> getRegisteredClients()
Returns the list of available client connectors.

Returns:
The list of available client connectors.

getRegisteredConverters

public List<ConverterHelper> getRegisteredConverters()
Returns the list of available converters.

Returns:
The list of available converters.

getRegisteredProtocols

public List<ProtocolHelper> getRegisteredProtocols()
Returns the list of available protocol connectors.

Returns:
The list of available protocol connectors.

getRegisteredServers

public List<ConnectorHelper<Server>> getRegisteredServers()
Returns the list of available server connectors.

Returns:
The list of available server connectors.

getUserClassLoader

public ClassLoader getUserClassLoader()
Returns the class loader specified by the user and that should be used in priority.

Returns:
The user class loader

registerDefaultAuthentications

public void registerDefaultAuthentications()
Registers the default authentication helpers.


registerDefaultConnectors

public void registerDefaultConnectors()
Registers the default client and server connectors.


registerDefaultConverters

public void registerDefaultConverters()
Registers the default converters.


registerDefaultProtocols

public void registerDefaultProtocols()
Registers the default protocols.


registerHelper

public void registerHelper(ClassLoader classLoader,
                           String provider,
                           List helpers,
                           Class constructorClass)
Registers a helper.

Parameters:
classLoader - The classloader to use.
provider - Bynary name of the helper's class.
helpers - The list of helpers to update.
constructorClass - The constructor parameter class to look for.

registerHelpers

public void registerHelpers(ClassLoader classLoader,
                            URL configUrl,
                            List<?> helpers,
                            Class<?> constructorClass)
Registers a helper.

Parameters:
classLoader - The classloader to use.
configUrl - Configuration URL to parse
helpers - The list of helpers to update.
constructorClass - The constructor parameter class to look for.

registerHelpers

public void registerHelpers(String descriptorPath,
                            List<?> helpers,
                            Class<?> constructorClass)
                     throws IOException
Registers a list of helpers.

Parameters:
descriptorPath - Classpath to the descriptor file.
helpers - The list of helpers to update.
constructorClass - The constructor parameter class to look for.
Throws:
IOException

registerUrlFactory

public void registerUrlFactory()
Registers a factory that is used by the URL class to create the URLConnection instances when the URL.openConnection() or URL.openStream() methods are invoked.

The implementation is based on the client dispatcher of the current context, as provided by Context.getCurrent() method.


setClassLoader

public void setClassLoader(ClassLoader newClassLoader)
Sets the engine class loader.

Parameters:
newClassLoader - The new user class loader to use.

setLoggerFacade

public void setLoggerFacade(LoggerFacade loggerFacade)
Sets the logger facade to use.

Parameters:
loggerFacade - The logger facade to use.

setRegisteredAuthenticators

public void setRegisteredAuthenticators(List<AuthenticatorHelper> registeredAuthenticators)
Sets the list of available authentication helpers.

Parameters:
registeredAuthenticators - The list of available authentication helpers.

setRegisteredClients

public void setRegisteredClients(List<ConnectorHelper<Client>> registeredClients)
Sets the list of available client helpers.

Parameters:
registeredClients - The list of available client helpers.

setRegisteredConverters

public void setRegisteredConverters(List<ConverterHelper> registeredConverters)
Sets the list of available converter helpers.

Parameters:
registeredConverters - The list of available converter helpers.

setRegisteredProtocols

public void setRegisteredProtocols(List<ProtocolHelper> registeredProtocols)
Sets the list of available protocol helpers.

Parameters:
registeredProtocols - The list of available protocol helpers.

setRegisteredServers

public void setRegisteredServers(List<ConnectorHelper<Server>> registeredServers)
Sets the list of available server helpers.

Parameters:
registeredServers - The list of available server helpers.

setUserClassLoader

public void setUserClassLoader(ClassLoader newClassLoader)
Sets the user class loader that should used in priority.

Parameters:
newClassLoader - The new user class loader to use.


Copyright © 2005-2013 Restlet.