org.codehaus.groovy.grails.commons
Interface GrailsApplication

All Superinterfaces:
ApplicationContextAware
All Known Implementing Classes:
DefaultGrailsApplication

public interface GrailsApplication
extends ApplicationContextAware

The main interface representing a running Grails application. This interface's main purpose is to provide a mechanism for analysing the conventions within a Grails application as well as providing metadata and information about the execution environment.

The GrailsApplication interface interfacts with ArtefactHandler instances which are capable of analysing different artefact types (controllers, domain classes etc.) and introspecting the artefact conventions

Implementors of this inteface should be aware that a GrailsApplication is only initialised when the initialise() method is called. In other words GrailsApplication instances are lazily initialised by the Grails runtime.

Since:
0.1 Created: Jul 2, 2005
Author:
Graeme Rocher, Steven Devijver
See Also:
initialise(), ArtefactHandler

Field Summary
static String APPLICATION_ID
          The id of the grails application within a bean context
static String CONFIG_CLASS
          The name of the class that provides configuration
static String DATA_SOURCE_CLASS
           
static String ENV_APPLICATION
          Deprecated. Use Environment.APPLICATION instead.
static String ENV_DEVELOPMENT
          Deprecated. Use Environment.DEVELOPMENT instead.
static String ENV_PRODUCTION
          Deprecated. Use Environment.PRODUCTION instead.
static String ENV_TEST
          Deprecated. Use Environment.TEST instead.
static String ENVIRONMENT
          Deprecated. Use Environment.KEY instead.
static String ENVIRONMENT_DEFAULT
          Deprecated. Use Environment.DEFAULT instead.
static String GLOBAL_PLUGINS_DIR
          Deprecated. Use BuildSettings.GLOBAL_PLUGINS_DIR instead.
static String PLUGINS_DIR
          Deprecated. Use BuildSettings.PLUGINS_DIR instead.
static String PROJECT_CLASSES_DIR
          Deprecated. Use BuildSettings.PROJECT_CLASSES_DIR instead.
static String PROJECT_META_FILE
           
static String PROJECT_RESOURCES_DIR
          Deprecated. Use BuildSettings.PROJECT_RESOURCES_DIR instead.
static String PROJECT_TEST_CLASSES_DIR
          Deprecated. Use BuildSettings.PROJECT_TEST_CLASSES_DIR instead.
static String PROJECT_WORK_DIR
          Deprecated. Use BuildSettings.PROJECT_WORK_DIR instead.
static String WORK_DIR
          Deprecated. Use BuildSettings.WORK_DIR instead.
 
Method Summary
 void addArtefact(Class artefact)
          Adds the given artefact, attempting to determine type from
 GrailsClass addArtefact(String artefactType, Class artefactClass)
          Registers a new artefact
 GrailsClass addArtefact(String artefactType, GrailsClass artefactGrailsClass)
          Registers a new artefact
 void addOverridableArtefact(Class artefact)
          Adds an artefact that can be overriden by user defined classes
 void configChanged()
          Fired to inform the application when the Config.groovy file changes
 Class[] getAllArtefacts()
          Retrieves all java.lang.Class instances considered Artefacts loaded by the Grails class loader
 Class[] getAllClasses()
          Retrieves all java.lang.Class instances loaded by the Grails class loader
 GrailsClass getArtefact(String artefactType, String name)
          Gets the GrailsClass associated with the named artefact class i.e. to get the GrailsClass for controller called "BookController" you pass the name "BookController"
 GrailsClass getArtefactByLogicalPropertyName(String type, String logicalName)
          Retrieves an artefact by its logical property name.
 GrailsClass getArtefactForFeature(String artefactType, Object featureID)
          Get an artefact GrailsClass by a "feature" which depending on the artefact may be a URI or tag name for example
 ArtefactHandler getArtefactHandler(String type)
          Returns the ArtefactHandler for the given type
 ArtefactHandler[] getArtefactHandlers()
          Obtain a list of all the artefact handlers
 ArtefactInfo getArtefactInfo(String artefactType)
          Obtain all the class information about the artefactType specified
 GrailsClass[] getArtefacts(String artefactType)
          Get an array of all the GrailsClass instances relating to artefacts of the specified type.
 ArtefactHandler getArtefactType(Class theClass)
          Returns the ArtefactHandler for the given class or null
 Class getClassForName(String className)
          Retrieves a class for the given name within the GrailsApplication or returns null
 ClassLoader getClassLoader()
          Returns the class loader instance for the Grails application
 groovy.util.ConfigObject getConfig()
          Returns the ConfigObject instance
 Map getFlatConfig()
          Returns the flatten ConfigObject for use from Java classes
 ApplicationContext getMainContext()
          Returns the Spring context for this application.
 Map getMetadata()
          Get access to the project's metadata, specified in application.properties This provides access to information like required grails version, application name, version etc but NOT general application settings.
 ApplicationContext getParentContext()
          Returns the Spring application context that contains this application instance.
 Resource getResourceForClass(Class theClazz)
          Retrieves a Resource instance for the given Grails class or null it doesn't exist
 boolean hasArtefactHandler(String type)
          Test whether an artefact handler exists for a given type
 void initialise()
          Initialise this GrailsApplication
 boolean isArtefact(Class theClazz)
          Call this to find out if the class you have is an artefact loaded by grails.
 boolean isArtefactOfType(String artefactType, Class theClazz)
          Check if the specified artefact Class has been loaded by Grails already AND is of the type expected
 boolean isArtefactOfType(String artefactType, String className)
          Check if the artefact Class with the name specified is of the type expected
 boolean isInitialised()
          Returns whether this GrailsApplication has been initialised or not
 boolean isWarDeployed()
          Returns true if this application has been deployed as a WAR file
 void rebuild()
          Rebuilds this Application throwing away the class loader and re-constructing it from the loaded resources again.
 void refresh()
          This method will refresh the entire application
 void refreshConstraints()
          This method will rebuild the constraint definitions
 void registerArtefactHandler(ArtefactHandler handler)
          Register a new artefact handler
 void setMainContext(ApplicationContext context)
          Sets the main Spring context for this application.
 
Methods inherited from interface org.springframework.context.ApplicationContextAware
setApplicationContext
 

Field Detail

WORK_DIR

static final String WORK_DIR
Deprecated. Use BuildSettings.WORK_DIR instead.
The name of the system property whose value contains the location, during development, of the Grails working directory where temporary files are generated to

See Also:
Constant Field Values

PROJECT_WORK_DIR

static final String PROJECT_WORK_DIR
Deprecated. Use BuildSettings.PROJECT_WORK_DIR instead.
The directory where temporary project resources and plug-ins are kept

See Also:
Constant Field Values

PLUGINS_DIR

static final String PLUGINS_DIR
Deprecated. Use BuildSettings.PLUGINS_DIR instead.
The path to the plug-ins directory for the application

See Also:
Constant Field Values

GLOBAL_PLUGINS_DIR

static final String GLOBAL_PLUGINS_DIR
Deprecated. Use BuildSettings.GLOBAL_PLUGINS_DIR instead.
The path to the global plug-ins directory for the application

See Also:
Constant Field Values

PROJECT_RESOURCES_DIR

static final String PROJECT_RESOURCES_DIR
Deprecated. Use BuildSettings.PROJECT_RESOURCES_DIR instead.
The name of the system property whose value contains the location, during development, of the current Grails projects resources directory

See Also:
Constant Field Values

PROJECT_CLASSES_DIR

static final String PROJECT_CLASSES_DIR
Deprecated. Use BuildSettings.PROJECT_CLASSES_DIR instead.
The name of the system property whose value contains the location, during development, of the current Grails projects resources directory

See Also:
Constant Field Values

PROJECT_TEST_CLASSES_DIR

static final String PROJECT_TEST_CLASSES_DIR
Deprecated. Use BuildSettings.PROJECT_TEST_CLASSES_DIR instead.
The name of the system property whose value contains the location, during development, of the current Grails projects resources directory

See Also:
Constant Field Values

APPLICATION_ID

static final String APPLICATION_ID
The id of the grails application within a bean context

See Also:
Constant Field Values

ENVIRONMENT

static final String ENVIRONMENT
Deprecated. Use Environment.KEY instead.
Constant used to resolve the environment via System.getProperty(ENVIRONMENT)


ENVIRONMENT_DEFAULT

static final String ENVIRONMENT_DEFAULT
Deprecated. Use Environment.DEFAULT instead.
Constants that indicates whether this GrailsApplication is running in the default environment

See Also:
Constant Field Values

ENV_DEVELOPMENT

static final String ENV_DEVELOPMENT
Deprecated. Use Environment.DEVELOPMENT instead.
Constant for the development environment


ENV_APPLICATION

static final String ENV_APPLICATION
Deprecated. Use Environment.APPLICATION instead.
Constant for the application data source, primarly for backward compatability for those applications that use ApplicationDataSource.groovy


ENV_PRODUCTION

static final String ENV_PRODUCTION
Deprecated. Use Environment.PRODUCTION instead.
Constant for the production environment.


ENV_TEST

static final String ENV_TEST
Deprecated. Use Environment.TEST instead.
Constant for the test environment.


CONFIG_CLASS

static final String CONFIG_CLASS
The name of the class that provides configuration

See Also:
Constant Field Values

DATA_SOURCE_CLASS

static final String DATA_SOURCE_CLASS
See Also:
Constant Field Values

PROJECT_META_FILE

static final String PROJECT_META_FILE
See Also:
Constant Field Values
Method Detail

getConfig

groovy.util.ConfigObject getConfig()
Returns the ConfigObject instance

Returns:
The ConfigObject instance

getFlatConfig

Map getFlatConfig()
Returns the flatten ConfigObject for use from Java classes

Returns:
The flattened config

getClassLoader

ClassLoader getClassLoader()

Returns the class loader instance for the Grails application

Returns:
The ClassLoader instance

getAllClasses

Class[] getAllClasses()
Retrieves all java.lang.Class instances loaded by the Grails class loader

Returns:
An array of classes

getAllArtefacts

Class[] getAllArtefacts()
Retrieves all java.lang.Class instances considered Artefacts loaded by the Grails class loader

Returns:
An array of classes

getMainContext

ApplicationContext getMainContext()
Returns the Spring context for this application. Note that this will return null until the application is fully initialised. This context contains all the application artifacts, plugin beans, the works.


setMainContext

void setMainContext(ApplicationContext context)
Sets the main Spring context for this application.


getParentContext

ApplicationContext getParentContext()
Returns the Spring application context that contains this application instance. It is the parent of the context returned by getMainContext().


getClassForName

Class getClassForName(String className)
Retrieves a class for the given name within the GrailsApplication or returns null

Parameters:
className - The name of the class
Returns:
The class or null

refreshConstraints

void refreshConstraints()
This method will rebuild the constraint definitions

To do:
move this out? Why ORM dependencies in here?

refresh

void refresh()
This method will refresh the entire application


rebuild

void rebuild()
Rebuilds this Application throwing away the class loader and re-constructing it from the loaded resources again. This method can only be called in development mode and an error will be thrown if called in a different enivronment


getResourceForClass

Resource getResourceForClass(Class theClazz)
Retrieves a Resource instance for the given Grails class or null it doesn't exist

Parameters:
theClazz - The Grails class
Returns:
A Resource or null

isArtefact

boolean isArtefact(Class theClazz)

Call this to find out if the class you have is an artefact loaded by grails.

Parameters:
theClazz - A class to test
Returns:
True if and only if the class was loaded from grails-app/
Since:
0.5

isArtefactOfType

boolean isArtefactOfType(String artefactType,
                         Class theClazz)

Check if the specified artefact Class has been loaded by Grails already AND is of the type expected

Parameters:
artefactType - A string identifying the artefact type to check for
theClazz - The class to check
Returns:
True if Grails considers the class to be managed as an artefact of the type specified.
Since:
0.5

isArtefactOfType

boolean isArtefactOfType(String artefactType,
                         String className)

Check if the artefact Class with the name specified is of the type expected

Parameters:
artefactType - A string identifying the artefact type to check for
className - The name of a class to check
Returns:
True if Grails considers the class to be managed as an artefact of the type specified.
Since:
0.5

getArtefact

GrailsClass getArtefact(String artefactType,
                        String name)

Gets the GrailsClass associated with the named artefact class

i.e. to get the GrailsClass for controller called "BookController" you pass the name "BookController"

Parameters:
artefactType - The type of artefact to retrieve, i.e. "Controller"
name - The name of an artefact such as "BookController"
Returns:
The associated GrailsClass or null
Since:
0.5

getArtefactType

ArtefactHandler getArtefactType(Class theClass)
Returns the ArtefactHandler for the given class or null

Parameters:
theClass - The class
Returns:
The ArtefactHandler

getArtefactInfo

ArtefactInfo getArtefactInfo(String artefactType)

Obtain all the class information about the artefactType specified

Parameters:
artefactType - An artefact type identifier i.e. "Domain"
Returns:
The artefact info or null if the artefactType is not recognized
Since:
0.5

getArtefacts

GrailsClass[] getArtefacts(String artefactType)

Get an array of all the GrailsClass instances relating to artefacts of the specified type.

Parameters:
artefactType - The type of artefact to retrieve, i.e. "Controller"
Returns:
An array of GrailsClasses which may empty by not null
Since:
0.5

getArtefactForFeature

GrailsClass getArtefactForFeature(String artefactType,
                                  Object featureID)

Get an artefact GrailsClass by a "feature" which depending on the artefact may be a URI or tag name for example

Parameters:
artefactType - The type ID of the artefact, i.e. "TagLib"
featureID - The "feature" ID, say a URL or tag name
Returns:
The grails class or null if none is found
Since:
0.5

addArtefact

GrailsClass addArtefact(String artefactType,
                        Class artefactClass)

Registers a new artefact

Parameters:
artefactType - The type ID of the artefact, i.e. "TagLib"
artefactClass - The class of the artefact. A new GrailsClass will be created automatically and added to internal structures, using the appropriate ArtefactHandler
Returns:
The new grails class for the artefact class
Since:
0.5

addArtefact

GrailsClass addArtefact(String artefactType,
                        GrailsClass artefactGrailsClass)

Registers a new artefact

Parameters:
artefactType - The type ID of the artefact, i.e. "TagLib"
artefactGrailsClass - The GrailsClass of the artefact.
Returns:
The supplied grails class for the artefact class
Since:
0.5

registerArtefactHandler

void registerArtefactHandler(ArtefactHandler handler)

Register a new artefact handler

Parameters:
handler - The new handler to add

hasArtefactHandler

boolean hasArtefactHandler(String type)

Test whether an artefact handler exists for a given type

Parameters:
type - The type of the handler
Returns:
True if it does

getArtefactHandlers

ArtefactHandler[] getArtefactHandlers()

Obtain a list of all the artefact handlers

Returns:
The list, possible empty but not null, of all currently registered handlers

initialise

void initialise()
Initialise this GrailsApplication


isInitialised

boolean isInitialised()
Returns whether this GrailsApplication has been initialised or not

Returns:
True if it has been initialised

getMetadata

Map getMetadata()

Get access to the project's metadata, specified in application.properties

This provides access to information like required grails version, application name, version etc but NOT general application settings.

Returns:
A read-only Map of data about the application, not environment specific

getArtefactByLogicalPropertyName

GrailsClass getArtefactByLogicalPropertyName(String type,
                                             String logicalName)
Retrieves an artefact by its logical property name. For example the logical property name of BookController would be book

Parameters:
type - The artefact type
logicalName - The logical name
Returns:
The GrailsClass or null if it doesn't exist

addArtefact

void addArtefact(Class artefact)
Adds the given artefact, attempting to determine type from

Parameters:
artefact - The artefact to add

isWarDeployed

boolean isWarDeployed()
Returns true if this application has been deployed as a WAR file

Returns:
True if the application is WAR deployed

addOverridableArtefact

void addOverridableArtefact(Class artefact)
Adds an artefact that can be overriden by user defined classes

Parameters:
artefact - An overridable artefact

configChanged

void configChanged()
Fired to inform the application when the Config.groovy file changes


getArtefactHandler

ArtefactHandler getArtefactHandler(String type)
Returns the ArtefactHandler for the given type

Parameters:
type - The artefact handler type
Returns:
The artefact handler


Copyright (c) 2005-2009 The Grails project