org.apache.tinkerpop.gremlin.jsr223

Interface GremlinScriptEngineManager

All Known Implementing Classes:

CachedGremlinScriptEngineManager, DefaultGremlinScriptEngineManager

public interface GremlinScriptEngineManager

The ScriptEngineManager implements a discovery, instantiation and configuration mechanism for GremlinScriptEngine classes and also maintains a collection of key/value pairs storing state shared by all engines created by it. This class uses the ServiceProvider mechanism to enumerate all the implementations of GremlinScriptEngineFactory. The ScriptEngineManager provides a method to return a list of all these factories as well as utility methods which look up factories on the basis of language name, file extension and mime type.

The Bindings of key/value pairs, referred to as the "Global Scope" maintained by the manager is available to all instances of @code ScriptEngine} created by the GremlinScriptEngineManager. The values in the Bindings are generally exposed in all scripts.

This interface is based quite heavily on the workings of the ScriptEngineManager supplied in the javax.script packages, but adds some additional features that are specific to Gremlin and TinkerPop. Unfortunately, it's not easily possible to extend ScriptEngineManager directly as there certain behaviors don't appear to be be straightforward to implement and member variables are all private. It is important to note that this interface is designed to provide support for "Gremlin-enabled" ScriptEngine instances (i.e. those that extend from GremlinScriptEngine) and is not meant to manage just any ScriptEngine instance that may be on the path.

Author:

Stephen Mallette (http://stephen.genoprime.com)

Method Summary

Modifier and Type	Method and Description
void	addModule(GremlinModule module) Add GremlinModule instances to customize newly created GremlinScriptEngine instances.
Object	get(String key) Gets the value for the specified key in the global scope.
Bindings	getBindings() Gets the bindings of the Bindings in global scope.
List<Customizer>	getCustomizers(String scriptEngineName) Get the list of Customizer instances filtered by the scriptEngineName.
GremlinScriptEngine	getEngineByExtension(String extension) Look up and create a GremlinScriptEngine for a given extension.
GremlinScriptEngine	getEngineByMimeType(String mimeType) Look up and create a GremlinScriptEngine for a given mime type.
GremlinScriptEngine	getEngineByName(String shortName) Looks up and creates a GremlinScriptEngine for a given name.
List<GremlinScriptEngineFactory>	getEngineFactories() Returns a list whose elements are instances of all the GremlinScriptEngineFactory classes found by the discovery mechanism.
void	put(String key, Object value) Sets the specified key/value pair in the global scope.
void	registerEngineExtension(String extension, GremlinScriptEngineFactory factory) Registers a GremlinScriptEngineFactory to handle an extension.
void	registerEngineMimeType(String type, GremlinScriptEngineFactory factory) Registers a GremlinScriptEngineFactory to handle a mime type.
void	registerEngineName(String name, GremlinScriptEngineFactory factory) Registers a GremlinScriptEngineFactory to handle a language name.
void	setBindings(Bindings bindings) Stores the specified Bindings as a global for all GremlinScriptEngine objects created by it.

Method Detail

setBindings

void setBindings(Bindings bindings)

Stores the specified Bindings as a global for all GremlinScriptEngine objects created by it.

Throws:

IllegalArgumentException - if bindings is null.

getBindings

Bindings getBindings()

Gets the bindings of the Bindings in global scope.

put

void put(String key,
         Object value)

Sets the specified key/value pair in the global scope. The key may not be null or empty.

Throws:

IllegalArgumentException - if key is null or empty.

get

Object get(String key)

Gets the value for the specified key in the global scope.

getEngineByName

GremlinScriptEngine getEngineByName(String shortName)

Looks up and creates a GremlinScriptEngine for a given name. The algorithm first searches for a GremlinScriptEngineFactory that has been registered as a handler for the specified name using the registerEngineExtension(String, GremlinScriptEngineFactory) method. If one is not found, it searches the set of GremlinScriptEngineFactory instances stored by the constructor for one with the specified name. If a ScriptEngineFactory is found by either method, it is used to create instance of GremlinScriptEngine.

Parameters:

shortName - The short name of the GremlinScriptEngine implementation returned by the ScriptEngineFactory.getNames() method.

Returns:

A GremlinScriptEngine created by the factory located in the search. Returns null if no such factory was found. The global scope of this manager is applied to the newly created GremlinScriptEngine

Throws:

NullPointerException - if shortName is null.

getEngineByExtension

GremlinScriptEngine getEngineByExtension(String extension)

Look up and create a GremlinScriptEngine for a given extension. The algorithm used by getEngineByName(String) is used except that the search starts by looking for a GremlinScriptEngineFactory registered to handle the given extension using registerEngineExtension(String, GremlinScriptEngineFactory).

Returns:

The engine to handle scripts with this extension. Returns null if not found.

Throws:

NullPointerException - if extension is null.

getEngineByMimeType

GremlinScriptEngine getEngineByMimeType(String mimeType)

Look up and create a GremlinScriptEngine for a given mime type. The algorithm used by getEngineByName(String) is used except that the search starts by looking for a GremlinScriptEngineFactory registered to handle the given mime type using registerEngineMimeType(String, GremlinScriptEngineFactory).

Parameters:

mimeType - The given mime type

Returns:

The engine to handle scripts with this mime type. Returns null if not found.

Throws:

NullPointerException - if mime-type is null.

getEngineFactories

List<GremlinScriptEngineFactory> getEngineFactories()

Returns a list whose elements are instances of all the GremlinScriptEngineFactory classes found by the discovery mechanism.

Returns:

List of all discovered GremlinScriptEngineFactory objects.

addModule

void addModule(GremlinModule module)

Add GremlinModule instances to customize newly created GremlinScriptEngine instances.

registerEngineName

void registerEngineName(String name,
                        GremlinScriptEngineFactory factory)

Registers a GremlinScriptEngineFactory to handle a language name. Overrides any such association found using the discovery mechanism.

Parameters:

name - The name to be associated with the GremlinScriptEngineFactory

factory - The class to associate with the given name.

Throws:

NullPointerException - if any of the parameters is null.

registerEngineMimeType

void registerEngineMimeType(String type,
                            GremlinScriptEngineFactory factory)

Registers a GremlinScriptEngineFactory to handle a mime type. Overrides any such association found using the discovery mechanism.

Parameters:

type - The mime type to be associated with the GremlinScriptEngineFactory.

factory - The class to associate with the given mime type.

Throws:

NullPointerException - if any of the parameters is null.

registerEngineExtension

void registerEngineExtension(String extension,
                             GremlinScriptEngineFactory factory)

Registers a GremlinScriptEngineFactory to handle an extension. Overrides any such association found using the discovery mechanism.

Parameters:

extension - The extension type to be associated with the GremlinScriptEngineFactory

factory - The class to associate with the given extension.

Throws:

NullPointerException - if any of the parameters is null.

getCustomizers

List<Customizer> getCustomizers(String scriptEngineName)

Get the list of Customizer instances filtered by the scriptEngineName.