pt.ist.fenixframework
Class FenixFramework

java.lang.Object
  pt.ist.fenixframework.FenixFramework

public class FenixFramework
extends Object

This is the main class for the Fenix Framework. It is the central point for obtaining most of the APIs that the user of the framework (a programmer) should need.

Before being able to use the framework, a program must initialize it, by providing a configuration. There are two (disjoint) alternative methods to initialize the FenixFramework:

• By convention: When the FenixFramework class is loaded, its static initialization code will check for the presence of a properties file that provides the configuration information.
• Explicitly: The programmer either creates a Config or MultiConfig instance and then explicitly calls the corresponding initialization method: initialize(Config) or initialize(MultiConfig).

Using the configuration by convention, the framework will first look up the name of the BackEnd that generated the domain-specific code (this is done by instantiating the class CurrentBackEndId and by requesting BackEndId.getBackEndName()) and then use that name to check for the presence of the file 'fenix-framework-<NNN>.properties' in the classpath using Thread.currentThread().getContextClassLoader().getResource() (where <NNN> is the name of the BackEnd). If this file is found, and contains the correct content, the framework will create the appropriate Config instance and automatically invoke initialize(Config). The syntax for the configuration file is to have each line in the form:

property=value

where each property must be the name of an existing configuration field. Additionally, there is one optional special property named config.class. By default, the config parser creates an instance of the BackEndId.getDefaultConfigClass() provided by the current BackEndId, but this property can be used to choose a different (albeit compatible) configuration class. The config instance is then populated with each property (except with the config.class property), using the following algorithm:

1. Confirm that the config has a field with the same name as the property. If not a ConfigError is thrown.
2. If the config class provides a method (can be private) in the format <property>FromString(String), then such method will be invoked to set the property. The String argument will be the value.
3. Else, attempt to directly set the property on the field assigning it the value String.
4. If all previous attempts have failed, throw a ConfigError.

The rationale supporting the previous mechanism is to allow the config class to process the String provided in the value> using the *FromString method.

After population of the config finishes with success, the initialize(Config) method is invoked with the created Config instance. From this point on, the initialization process continues just as if the programmer had explicitly invoked that initialization method.

The explicit configuration maintains the original configuration style (since Fenix Framework 1.0) with compile-time checking of the config's attributes. To use it, read the documentation in the Config class. It also adds the possibility for the programmer to provide multiple configurations and then let the initialization process decide which to use based on the current BackEnd (see MultiConfig for more details).

After initialization completes with success, the framework is ready to manage operations on the domain objects. Also, it is possible to get an instance of the DomainModel class representing the structure of the application's domain.

See Also:

Config, DomainModel

Constructor Summary

FenixFramework()

Method Summary

static Config	getConfig()
static DomainModel	getDomainModel() Gets the model of the domain classes.
static <T extends DomainObject> T	getDomainObject(String externalId) Get any DomainObject given its external identifier.
static DomainRoot	getDomainRoot() Always gets a well-known singleton instance of DomainRoot.
static Transaction	getTransaction()
static TransactionManager	getTransactionManager()
static void	initialize(Config newConfig) This method initializes the FenixFramework.
static void	initialize(MultiConfig configs)
static boolean	isInitialized()
static void	shutdown() Inform the framework components that the application intends to shutdown.

Methods inherited from class java.lang.Object

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

Constructor Detail

FenixFramework

public FenixFramework()

Method Detail

isInitialized

public static boolean isInitialized()

Returns:

whether the FenixFramework.initialize method has already been invoked

initialize

public static void initialize(Config newConfig)

This method initializes the FenixFramework. It must be the first method to be called, and it should be invoked only once. It needs to be called before starting to access any Transactions/DomainObjects, etc.

Parameters:

newConfig - The configuration that will be used by this instance of the framework.

initialize

public static void initialize(MultiConfig configs)

getConfig

public static Config getConfig()

getDomainModel

public static DomainModel getDomainModel()

Gets the model of the domain classes. Should only be invoked after the framework is initialized.

Returns:

The current DomainModel in use.

Throws:

ConfigError - If this method is invoked before the framework is initialized or if a DmlCompilerException occurs (only possible on first invocation).

getDomainRoot

public static DomainRoot getDomainRoot()

Always gets a well-known singleton instance of DomainRoot. The intended use of this instance is to provide a single entry point to the graph of DomainObjects. The user of the framework may connect (via DML) any DomainObject to this class.

getDomainObject

public static <T extends DomainObject> T getDomainObject(String externalId)

Get any DomainObject given its external identifier. The external identifier must have been obtained by a previous invocation to DomainObject.getExternalId(). If the external identifier is tampered with (in which case a valid DomainObject cannot be found), the result of calling this method is undefined.

Parameters:

externalId - The external identifier of the domain object to get

Returns:

The domain object requested

getTransactionManager

public static TransactionManager getTransactionManager()

getTransaction

public static Transaction getTransaction()

shutdown

public static void shutdown()

Inform the framework components that the application intends to shutdown. This allows for an orderly termination of any running components. The default implementation delegates to the backend the task of shutting down the framework. After invoking this method there is no guarantee that the Fenix Framework is able to provide any more services.