org.openquark.cal.services
Class BasicCALServices

java.lang.Object
  org.openquark.cal.services.BasicCALServices

public final class BasicCALServices
extends Object

This is a helper class to assist CAL clients with creating and using some of the basic CAL services. It handles initialization and compilation of a workspace, provision of some basic CAL service objects, and contains some helper methods for filtering gems and running code.

Author:

Edward Lam, Rick Cameron, mbyne

Nested Class Summary

static class

BasicCALServices.Config This class is used to encapsulate BasicCALServices configuration properties.

Method Summary

CompilerMessage.Severity	addNewModule(ModuleSourceDefinition sourceDefinition, CompilerMessageLogger logger) Compile the source definition for a module and add it to the program
EntryPointSpec	addNewModuleWithFunction(ModuleName newModuleName, SourceModel.FunctionDefn functionDefintion) Add a new module containing the specified function to the program.
EntryPointSpec	addNewModuleWithFunction(ModuleName newModuleName, SourceModel.Import[] imports, SourceModel.FunctionDefn functionDefinition, SourceModel.FunctionTypeDeclaration functionTypeDeclaration) Add a new module containing the specified function, type declaration and imports to the program.
boolean	compileWorkspace(StatusListener programStatusListener, CompilerMessageLogger logger) Compile the workspace.
Set<GemEntity>	findGemsByReturnType(ModuleName scopeModule, String returnTypeName, boolean sortGems) Returns a set containing the public gems in the workspace which have the specified return type.
Set<GemEntity>	findGemsOfType(ModuleName scopeModule, String typeName, boolean sortGems) Returns a Set containing the public gems in the workspace which have the specified type signature.
CALWorkspace	getCALWorkspace()
ProgramModelManager.CompilationOptions	getCompilationOptions() Get compiler options
Compiler	getCompiler()
GemEntity	getGemEntity(QualifiedName gemName) Returns the entity corresponding to the specified qualified name.
Set<GemEntity>	getMatchingGems(GemFilter filter) Returns public gems in the workspace that match the given filter
Set<GemEntity>	getMatchingGems(GemFilter filter, boolean sortGems) Returns public gems in the workspace that match the given filter.
ModuleTypeInfo	getModuleTypeInfo(ModuleName moduleName) Get the type info for a module
PreludeTypeConstants	getPreludeTypeConstants() Note: must have a compiled workspace in hand before these will be available.
TypeChecker	getTypeChecker()
TypeChecker.TypeCheckInfo	getTypeCheckInfo(ModuleName moduleName) Get the type checker info for a module
TypeExpr	getTypeFromQualifiedName(QualifiedName name) This returns a type expression for the type represented by the qualified name the type expression is evaluated within the scope of the type's defining module
TypeExpr	getTypeFromString(ModuleName module, String typeString) Returns the type expression corresponding to the specified string.
WorkspaceManager	getWorkspaceManager()
static BasicCALServices	make(String workspaceFileName) The simplest factory method to create a BasicCALServices instance.
static BasicCALServices	make(String workspaceFileProperty, String defaultWorkspaceFileName, String defaultWorkspaceClientID) Factory method for this class.
static BasicCALServices	make(String workspaceFileProperty, String defaultWorkspaceFileName, String defaultWorkspaceClientID, BasicCALServices.Config config) Factory method for this class.
static BasicCALServices	makeCompiled(String workspaceFileName, CompilerMessageLogger messageLogger) The simplest factory method to create a BasicCALServices instance.
static BasicCALServices.Config	makeConfig() makes a new BasicCALServices configuarion with default properties
void	prepareFunctions(List<EntryPointSpec> entryPointSpecs) This method pre-caches a list of entryPointSpecs for invocation with runFunction.
boolean	recompileWorkspace(CompilerMessageLogger logger) Recompile the workspace.
Object	runFunction(EntryPointSpec entryPointSpec, ExecutionContext executionContext, Object[] args) runs an existing function and returns the result.
Object	runFunction(EntryPointSpec entryPointSpec, Object[] args) Runs an existing CAL function and returns the result.
void	setCompilationOptions(ProgramModelManager.CompilationOptions options) set the compilation options - if they are not set default compilation options will be used

Methods inherited from class java.lang.Object

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

Method Detail

make

public static BasicCALServices make(String workspaceFileName)

The simplest factory method to create a BasicCALServices instance.

Parameters:

workspaceFileName - name of the workspace from the StandardVault e.g. "cal.platform.test.cws"

Returns:

the BasicCALServices instance, or null if initialization failed

makeCompiled

public static BasicCALServices makeCompiled(String workspaceFileName,
                                            CompilerMessageLogger messageLogger)

The simplest factory method to create a BasicCALServices instance. It ensures that the CAL workspace is compiled and ready to use. This is all that is needed in most cases.

Parameters:

workspaceFileName -

messageLogger - all messages created during the compilation of the workspace are appended to the messageLogger

Returns:

the compiled CAL services, or null if initialization or compilation failed

make

public static BasicCALServices make(String workspaceFileProperty,
                                    String defaultWorkspaceFileName,
                                    String defaultWorkspaceClientID)

Factory method for this class.

Parameters:

workspaceFileProperty - If non-null, the value of this system property represents the file system pathname of the workspace file to be used to instantiate the workspace. If null, defaultWorkspaceFileName will be used.

defaultWorkspaceFileName - This workspace file from the StandardVault will be used if the workspaceFileProperty system property is not set.

defaultWorkspaceClientID - a string identifying the default client for this workspace. Client id's are used to refer to specific workspaces. This id will be used, unless the property indicated by CALWorkspace.WORKSPACE_PROP_CLIENT_ID is set, in which case the property value will be used. If the client id is null, the workspace is nullary.

Returns:

the BasicCALServices instance, or null if initialization failed

make

public static BasicCALServices make(String workspaceFileProperty,
                                    String defaultWorkspaceFileName,
                                    String defaultWorkspaceClientID,
                                    BasicCALServices.Config config)

Factory method for this class.

Parameters:

workspaceFileProperty - If non-null, the value of this system property represents the file system pathname of the workspace file to be used to instantiate the workspace. If null, defaultWorkspaceFileName will be used.

defaultWorkspaceFileName - This workspace file from the StandardVault will be used if the workspaceFileProperty system property is not set.

defaultWorkspaceClientID - a string identifying the default client for this workspace. Client id's are used to refer to specific workspaces. This id will be used, unless the property indicated by CALWorkspace.WORKSPACE_PROP_CLIENT_ID is set, in which case the property value will be used. If the client id is null, the workspace is nullary.

config - this parameter controls the configuration of the BasicCALServices that is created

Returns:

the BasicCALServices instance, or null if initialization failed

makeConfig

public static BasicCALServices.Config makeConfig()

makes a new BasicCALServices configuarion with default properties

Returns:

a new default config

getWorkspaceManager

public WorkspaceManager getWorkspaceManager()

Returns:

the workspace manager.

getPreludeTypeConstants

public PreludeTypeConstants getPreludeTypeConstants()

Note: must have a compiled workspace in hand before these will be available.

Returns:

handy TypeExpr constants for common Prelude types.

compileWorkspace

public boolean compileWorkspace(StatusListener programStatusListener,
                                CompilerMessageLogger logger)

Compile the workspace.

Parameters:

programStatusListener - if non-null, the listener on the status of the compilation.

logger - the logger used to log error messages during compilation.

Returns:

true if the compilation was successful

recompileWorkspace

public boolean recompileWorkspace(CompilerMessageLogger logger)

Recompile the workspace.

Returns:

true if the compilation was successful, false otherwise.

getCALWorkspace

public CALWorkspace getCALWorkspace()

Returns:

the CAL workspace.

getCompiler

public Compiler getCompiler()

Returns:

an associated Compiler

getTypeChecker

public TypeChecker getTypeChecker()

Returns:

the associated TypeChecker

getModuleTypeInfo

public ModuleTypeInfo getModuleTypeInfo(ModuleName moduleName)

Get the type info for a module

Parameters:

moduleName - the name of the module

Returns:

the type info for the module

getTypeCheckInfo

public TypeChecker.TypeCheckInfo getTypeCheckInfo(ModuleName moduleName)

Get the type checker info for a module

Returns:

the TypeCheckInfo for a module

getGemEntity

public GemEntity getGemEntity(QualifiedName gemName)

Returns the entity corresponding to the specified qualified name.

Parameters:

gemName - the name of the entity to retrieve.

Returns:

the corresponding gem entity, or null if it is not found.

getTypeFromQualifiedName

public TypeExpr getTypeFromQualifiedName(QualifiedName name)

This returns a type expression for the type represented by the qualified name the type expression is evaluated within the scope of the type's defining module

Parameters:

name - the types qualified name

Returns:

type expression representing the qualified type name

getTypeFromString

public TypeExpr getTypeFromString(ModuleName module,
                                  String typeString)

Returns the type expression corresponding to the specified string.

Parameters:

module - the type string is compiled w.r.t to this module

typeString - a string representation a CAL type.

Returns:

a type expression object corresponding to the string, or null if the string couldn't be converted to a type.

getMatchingGems

public Set<GemEntity> getMatchingGems(GemFilter filter)

Returns public gems in the workspace that match the given filter

Parameters:

filter - a gem filter.

Returns:

public gems in the workspace which pass the filter.

getMatchingGems

public Set<GemEntity> getMatchingGems(GemFilter filter,
                                      boolean sortGems)

Returns public gems in the workspace that match the given filter.

Parameters:

filter - a gem filter.

sortGems - If true, then the gems will be sorted alphabetically.

Returns:

public gems in the workspace which pass the filter.

findGemsOfType

public Set<GemEntity> findGemsOfType(ModuleName scopeModule,
                                     String typeName,
                                     boolean sortGems)

Returns a Set containing the public gems in the workspace which have the specified type signature.

Parameters:

scopeModule - this is the module that is used for scope

typeName - the type signature of the gems to be found

sortGems - If true, then the gems will be sorted alphabetically.

Returns:

a set of the matching gems

findGemsByReturnType

public Set<GemEntity> findGemsByReturnType(ModuleName scopeModule,
                                           String returnTypeName,
                                           boolean sortGems)

Returns a set containing the public gems in the workspace which have the specified return type.

Parameters:

scopeModule - this is the module that is used for compiling the type

returnTypeName - the type name of the return type for the gems to be found

sortGems - If true, then the gems will be sorted alphabetically.

Returns:

(Set of GemEntity) a set of the matching gems

addNewModule

public CompilerMessage.Severity addNewModule(ModuleSourceDefinition sourceDefinition,
                                             CompilerMessageLogger logger)

Compile the source definition for a module and add it to the program

Parameters:

sourceDefinition - the module's source definition.

logger - the logger used to log error messages during compilation.

Returns:

the max error severity from the compile.

addNewModuleWithFunction

public EntryPointSpec addNewModuleWithFunction(ModuleName newModuleName,
                                               SourceModel.FunctionDefn functionDefintion)
                                        throws GemCompilationException

Add a new module containing the specified function to the program. Imports are computed automatically based on the function. If the module already exists its' contents are replaced by the funcDefn.

Parameters:

newModuleName -

functionDefintion -

Returns:

an EntryPointSpec with default input/output policies for the new function.

Throws:

GemCompilationException

addNewModuleWithFunction

public EntryPointSpec addNewModuleWithFunction(ModuleName newModuleName,
                                               SourceModel.Import[] imports,
                                               SourceModel.FunctionDefn functionDefinition,
                                               SourceModel.FunctionTypeDeclaration functionTypeDeclaration)
                                        throws GemCompilationException

Add a new module containing the specified function, type declaration and imports to the program. If the module already exists its' contents are replaced by the funcDefn.

Parameters:

newModuleName -

imports - - if this is null the imports are computed based on the function definition

functionDefinition -

functionTypeDeclaration - the type declaration for the function, this may be null

Returns:

an EntryPointSpec, with default input/output policies, for the new function.

Throws:

GemCompilationException

runFunction

public Object runFunction(EntryPointSpec entryPointSpec,
                          Object[] args)
                   throws CALExecutorException,
                          GemCompilationException

Runs an existing CAL function and returns the result. A new default execution context is created to run the function, and then destroyed. It is worthwhile to consider creating an execution context separately and using it for all calls to runFunction, as this can be more efficient, allowing certain results to be cached between executions.

Parameters:

entryPointSpec - defines the function to run and the input and output policies to use.

args - the arguments to pass to the function - may be null if there are no arguments

Returns:

the result of running the function.

Throws:

CALExecutorException

GemCompilationException

See Also:

runFunction(EntryPointSpec, ExecutionContext, Object[])

runFunction

public Object runFunction(EntryPointSpec entryPointSpec,
                          ExecutionContext executionContext,
                          Object[] args)
                   throws CALExecutorException,
                          GemCompilationException

runs an existing function and returns the result. It uses the supplied execution context. It is generally much more efficient to use this version of runFunction, as it allows CAFs can be cached between calls.

Parameters:

entryPointSpec - defines the function to run and the input and output policies to use.

args - the arguments to pass to the function - may be null if there are no arguments.

Returns:

the result of running the function.

Throws:

CALExecutorException

GemCompilationException

prepareFunctions

public void prepareFunctions(List<EntryPointSpec> entryPointSpecs)
                      throws GemCompilationException

This method pre-caches a list of entryPointSpecs for invocation with runFunction. It is not necessary to use this method before using run function, but in some circumstances it can improve performance. When runFunction is invoked on an entryPointSpec for the first time, the CAL compiler must do some work in the target module. If you intend to use many entryPointSpecs for the same module, invoking this function with a list of the entryPointSpecs allows the CAL compiler to prepare them all in a single step, which can be more efficient. If you run only a single function (even many times) in any given module, or are not concerned by the cost of the first call to runFunction for each entryPointSpec, there is no need to use this function.

Parameters:

entryPointSpecs - a list of entry point specs that will be used later by runFunction.

Throws:

GemCompilationException

getCompilationOptions

public ProgramModelManager.CompilationOptions getCompilationOptions()

Get compiler options

setCompilationOptions

public void setCompilationOptions(ProgramModelManager.CompilationOptions options)

set the compilation options - if they are not set default compilation options will be used

Parameters:

options - the compilation options to use when running code.