er.extensions

Class ERXExtensions

java.lang.Object

er.extensions.ERXFrameworkPrincipal

er.extensions.ERXExtensions

public class ERXExtensions
extends ERXFrameworkPrincipal

Principal class of the ERExtensions framework. This class will be loaded at runtime when the ERExtensions bundle is loaded (even before the Application constructor is called) This class has a boat-load of stuff in it that will hopefully be finding better homes in the future. This class serves as the initialization point of this framework, look in the static initializer to see all the stuff that is initially setup when this class is loaded. This class also has a boat load of string, array and EOF utilities as well as the factory methods for creating editing contexts with the default delegates set.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ERXExtensions.KeyValueQualifierSQLGenerationSupport Support class that listens for EOKeyValueQualifiers that have a selector that was registered and uses their support instead.

Nested classes/interfaces inherited from class er.extensions.ERXFrameworkPrincipal

ERXFrameworkPrincipal.Observer

Field Summary

Fields

Modifier and Type	Field and Description
static org.apache.log4j.Logger	adaptorLogger logging support for the adaptor channel
protected ERXModelGroup	defaultModelGroup holds the default model group
static String	eoAdaptorLoggingWillChangeNotification Notification name, posted before EOAdaptor debug logging will change its setting.
static String	objectsWillChangeInEditingContext Notification name, posted before object will change in an editing context
static org.apache.log4j.Logger	sharedEOadaptorLogger logging support for shared object loading

Fields inherited from class er.extensions.ERXFrameworkPrincipal

initializedFrameworks, launchingFrameworks, log

Constructor Summary

Constructors

Constructor and Description
ERXExtensions()

Method Summary

Modifier and Type	Method and Description
static boolean	adaptorLogging() Returns the current state of EOAdaptor logging.
static void	addObjectToBothSidesOfPotentialRelationshipFromObjectWithKeyPath(EOEnterpriseObject to, EOEnterpriseObject from, String keyPath) This method handles 3 different cases 1.
static void	addRandomizeDirectActionURL(StringBuffer daURL) This method can be used with Direct Action URLs to make sure that the browser will reload the page.
static String	addSessionIdFormValue(String urlString, WOSession session) Adds the session ID for a given session to a given URL.
static boolean	booleanFlagOnSessionForKeyWithDefault(WOSession s, String key, boolean defaultValue) Retrieves a value from the session's dictionary and evaluates that object using the booleanValue method of ERXValueUtilities.
void	bundleDidLoad(NSNotification n)
static void	configureAdaptorContext() This method is called by the delegate when the configuration file is changed.
void	configureAdaptorContext(NSNotification n) This method is called every time the configuration file is changed.
static void	configureAdaptorContextRapidTurnAround(Object anObserver) Configures the passed in observer to register a call back when the configuration file is changed.
EOModelGroup	defaultModelGroup() Delegate method for the EOModelGroup class delegate.
void	didFinishInitialization() Overridden by subclasses to finalize framework initialization.
void	finishInitialization() This method is called when the application has finished launching.
static void	forceGC(int maxLoop) Forces the garbage collector to run.
static void	freeProcessResources(Process p) Deprecated. use ERXRuntimeUtilities.freeProcessResources(Process) instead
static void	initApp(Class applicationSubclass, String[] args) Initializes your WOApplication programmatically (for use in test cases and main methods) with the assumption that the current directory is your main bundle URL.
static void	initApp(String mainBundleName, Class applicationSubclass, String[] args) Initializes your WOApplication programmatically (for use in test cases and main methods).
static void	initApp(String mainBundleName, URL mainBundleURL, Class applicationSubclass, String[] args) Initializes your WOApplication programmatically (for use in test cases and main methods).
static void	initEOF(File mainBundleFolder, String[] args) Initializes Wonder EOF programmatically (for use in test cases and main methods).
static void	initEOF(File mainBundleFile, String[] args, boolean assertsBundleExists) Initializes Wonder EOF programmatically (for use in test cases and main methods).
static void	initEOF(File mainBundleFile, String[] args, boolean assertsBundleExists, boolean assertsBundleIsWOApplicationFolder, boolean fallbackToUserDirAsBundle) Initializes Wonder EOF programmatically (for use in test cases and main methods).
static void	initEOF(String[] args) Initializes Wonder EOF programmatically (for use in test cases and main methods).
protected void	initialize() Configures the framework.
static boolean	objectImplementsMethod(Object object, String methodName, Class[] parameters) Determines if a given object implements a method given the name and the array of input parameters.
static String	randomizeDirectActionURL(String daURL) This method can be used with Direct Action URLs to make sure that the browser will reload the page.
static void	refreshSharedObjectsWithName(String entityName) Refreshes all of the shared enterprise objects for a given shared entity, then notifies the entity's class by calling the static method sharedEntityDataWasRefreshed() if the shared entity implements it.
static void	refreshSharedObjectsWithNames(NSArray names) Refreshes all of the objects for an array of entity names.
static void	registerSQLSupportForSelector(NSSelector selector, EOQualifierSQLGeneration.Support support)
static String	resolveUnit(String userInfoUnitString, EOEnterpriseObject object, String prefixKeyPath) Resolves a given user info unit string for a given object.
static void	setAdaptorLogging(boolean onOff) Turn EOAdaptor logging on and off.
static void	setBooleanFlagOnSessionForKey(WOSession s, String key, boolean newValue) Uses the setObjectForKey method of the WOSession class to push a Boolean object onto the session for a given key.
void	sharedEditingContextWasInitialized(NSNotification n) This method is called for the following notification EOSharedEditingContext.DefaultSharedEditingContextWasInitializedNotification
static String	userInfoUnit(EOEnterpriseObject object, String key) For a given enterprise object and key path, will return what the key 'unit' returns from the userInfo dictionary of the last property of the key path's EOAttribute or EORelationship.
static String	userPreferencesKeyFromContext(String key, NSKeyValueCoding context) Constructs a unique key based on a context.

Methods inherited from class er.extensions.ERXFrameworkPrincipal

hasFrameworkInstalled, setUpFrameworkPrincipalClass, sharedInstance, toString

Methods inherited from class java.lang.Object

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

Field Detail

objectsWillChangeInEditingContext

public static final String objectsWillChangeInEditingContext

Notification name, posted before object will change in an editing context

See Also:

Constant Field Values

eoAdaptorLoggingWillChangeNotification

public static final String eoAdaptorLoggingWillChangeNotification

Notification name, posted before EOAdaptor debug logging will change its setting.

See Also:

Constant Field Values

defaultModelGroup

protected volatile ERXModelGroup defaultModelGroup

holds the default model group

adaptorLogger

public static org.apache.log4j.Logger adaptorLogger

logging support for the adaptor channel

sharedEOadaptorLogger

public static org.apache.log4j.Logger sharedEOadaptorLogger

logging support for shared object loading

Constructor Detail

ERXExtensions

public ERXExtensions()

Method Detail

defaultModelGroup

public EOModelGroup defaultModelGroup()

Delegate method for the EOModelGroup class delegate.

Returns:

a fixed ERXModelGroup

initialize

protected void initialize()

Configures the framework. All the bits and pieces that need to be configured are configured, those that need to happen later are delayed by registering an observer for notifications that are posted when the application is finished launching. This public observer is used to perform basic functions in response to notifications. Specifically it handles configuring the adaptor context so that SQL debugging can be enabled and disabled on the fly through the log4j system. Handling cleanup issues when sessions timeout, i.e. releasing all references to editing contexts created for that session. Handling call all of the did* methods on ERXGenericRecord subclasses after an editing context has been saved. This delegate is also responsible for configuring ERXValidationFactory. This delegate is configured when this framework is loaded.

Overrides:

initialize in class ERXFrameworkPrincipal

bundleDidLoad

public void bundleDidLoad(NSNotification n)

finishInitialization

public void finishInitialization()

This method is called when the application has finished launching. Here is where log4j is configured for rapid turn around and the validation template system is configured.

Specified by:

finishInitialization in class ERXFrameworkPrincipal

didFinishInitialization

public void didFinishInitialization()

Description copied from class: ERXFrameworkPrincipal

Overridden by subclasses to finalize framework initialization.

Overrides:

didFinishInitialization in class ERXFrameworkPrincipal

registerSQLSupportForSelector

public static void registerSQLSupportForSelector(NSSelector selector,
                                                 EOQualifierSQLGeneration.Support support)

configureAdaptorContext

public void configureAdaptorContext(NSNotification n)

This method is called every time the configuration file is changed. This allows for turning SQL debugging on and off at runtime.

Parameters:

n - notification posted when the configuration file changes.

sharedEditingContextWasInitialized

public void sharedEditingContextWasInitialized(NSNotification n)

This method is called for the following notification EOSharedEditingContext.DefaultSharedEditingContextWasInitializedNotification

Parameters:

n - the notification.

configureAdaptorContextRapidTurnAround

public static void configureAdaptorContextRapidTurnAround(Object anObserver)

Configures the passed in observer to register a call back when the configuration file is changed. This allows one to change a logger's setting and have that changed value change the NSLog setting to log the generated SQL. This method is called as part of the framework initialization process.

Parameters:

anObserver - object to register the call back with.

configureAdaptorContext

public static void configureAdaptorContext()

This method is called by the delegate when the configuration file is changed. It's sole purpose is to map a logging logger to a debug group. Hopefully in the future we will have a more generic solution.

adaptorLogging

public static boolean adaptorLogging()

Returns the current state of EOAdaptor logging.

setAdaptorLogging

public static void setAdaptorLogging(boolean onOff)

Turn EOAdaptor logging on and off.

Parameters:

onOff -

forceGC

public static void forceGC(int maxLoop)

Forces the garbage collector to run. The max loop parameter determines the maximum number of times to run the garbage collector if the memory footprint is still going down. In normal cases you would just need to call this method with the parameter 1. If called with the parameter 0 the garbage collector will continue to run until no more free memory is available to collect.

Note: This can be a very costly operation and should only be used in extreme circumstances.

Parameters:

maxLoop - maximum times to run the garbage collector. Passing in 0 will cause the collector to run until all free objects have been collected.

addObjectToBothSidesOfPotentialRelationshipFromObjectWithKeyPath

public static void addObjectToBothSidesOfPotentialRelationshipFromObjectWithKeyPath(EOEnterpriseObject to,
                                                                                    EOEnterpriseObject from,
                                                                                    String keyPath)

This method handles 3 different cases 1. keyPath is a single key and represents a relationship --> addObjectToBothSidesOfRelationshipWithKey 2. keyPath is a single key and does NOT represents a relationship 3. keyPath is a real key path: break it up, navigate to the last atom --> back to 1. or 2.

Parameters:

to - enterprise object that is having objects added to it

from - enterprise object that is providing the objects

keyPath - that specifies the relationship on the to object to add the objects to.

userInfoUnit

public static String userInfoUnit(EOEnterpriseObject object,
                                  String key)

For a given enterprise object and key path, will return what the key 'unit' returns from the userInfo dictionary of the last property of the key path's EOAttribute or EORelationship. The userInfo dictionary can be edited via EOModeler, it is that open book looking icon when looking at either an attribute or relationship.

For example if the userInfo dictionary or the attribute 'speed' on the entity Car contained the key-value pair unit=mph, then this method would be able to resolve that unit given either of these keypaths:

userInfoUnit(aCar, "speed");
userInfoUnit(aDrive, "toCar.speed");

Units can be very useful for adding meta information to particular attributes and relationships in models. The ERDirectToWeb framework adds support for displaying units.

Parameters:

object - to resolve the key-path from

key - path off of the object

Returns:

unit information stored in the userInfo dictionary

resolveUnit

public static String resolveUnit(String userInfoUnitString,
                                 EOEnterpriseObject object,
                                 String prefixKeyPath)

Resolves a given user info unit string for a given object. User info values are stored in an EOAttibute or EORelationship's userInfo dictionary. See the method userInfoUnit for a better description of getting values out of the userInfo dictionary. This method deals with resolving dynamic userInfo keys. These keys need to start with the '@@' symbol. For instance if you have the user info value '@unit' off of an attribute for the entity Movie, then you can either pass in a Movie object or a different object with a prefix key path to a movie object.

Parameters:

userInfoUnitString - string to be resolved, needs to start with '@@'. This keypath will be evaluated against either the object if no prefixKeyPath is specified or the object returned by the prefixKeyPath being evaluated against the object passed in.

object - to resolve either the user info unit or the prefixKeyPath.

prefixKeyPath - used as a prefix for the unit resolution.

Returns:

the resolved unit from the object.

refreshSharedObjectsWithNames

public static void refreshSharedObjectsWithNames(NSArray names)

Refreshes all of the objects for an array of entity names.

Parameters:

names - array of shared entity names

refreshSharedObjectsWithName

public static void refreshSharedObjectsWithName(String entityName)

Refreshes all of the shared enterprise objects for a given shared entity, then notifies the entity's class by calling the static method sharedEntityDataWasRefreshed() if the shared entity implements it.

Parameters:

entityName - name of the shared entity

randomizeDirectActionURL

public static String randomizeDirectActionURL(String daURL)

This method can be used with Direct Action URLs to make sure that the browser will reload the page. This is done by adding the parameter [? | &]r=random_number to the end of the url.

Parameters:

daURL - a url to add the randomization to.

Returns:

url with the addition of the randomization key

addRandomizeDirectActionURL

public static void addRandomizeDirectActionURL(StringBuffer daURL)

This method can be used with Direct Action URLs to make sure that the browser will reload the page. This is done by adding the parameter [? | &]r=random_number to the end of the url.

Parameters:

daURL - a url to add the randomization to.

addSessionIdFormValue

public static String addSessionIdFormValue(String urlString,
                                           WOSession session)

Adds the session ID for a given session to a given URL.

Parameters:

urlString - URL string to add session ID form value to

session - session object

Returns:

URL with the addition of session ID form value

setBooleanFlagOnSessionForKey

public static void setBooleanFlagOnSessionForKey(WOSession s,
                                                 String key,
                                                 boolean newValue)

Uses the setObjectForKey method of the WOSession class to push a Boolean object onto the session for a given key. Note this is not using key value coding, meaning you don't need to have a boolean instance variable corresponding to the given key on your session object. This flag can be retrieved using the method booleanFlagOnSessionForKeyWithDefault.

Parameters:

s - session object on which to set the boolean flag

key - to be used in the session's dictionary

newValue - boolean value to be set on the session

booleanFlagOnSessionForKeyWithDefault

public static boolean booleanFlagOnSessionForKeyWithDefault(WOSession s,
                                                            String key,
                                                            boolean defaultValue)

Retrieves a value from the session's dictionary and evaluates that object using the booleanValue method of ERXValueUtilities. If there is no object corresponding to the key passed in, then the default value is returned. The usual way in which boolean values are set on the session object is by using the method setBooleanFlagOnSessionForKey in this class.

Parameters:

s - session object to retrieve the boolean flag from

key - that the boolean is stored under

defaultValue - value to be returned if the object in the dictionary is null

Returns:

boolean value of the object stored in the session's dictionary for the given key.

userPreferencesKeyFromContext

public static String userPreferencesKeyFromContext(String key,
                                                   NSKeyValueCoding context)

Constructs a unique key based on a context. A method used by the preferences mechanism from ERDirectToWeb which needs to be here because it is shared by ERDirectToWeb and ERCoreBusinessLogic.

Parameters:

key - preference key

context - most likely a d2wContext object

Returns:

a unique preference key for storing and retrieving preferences

freeProcessResources

@Deprecated
public static void freeProcessResources(Process p)

Deprecated. use ERXRuntimeUtilities.freeProcessResources(Process) instead

Frees all of the resources associated with a given process and then destroys the process.

Parameters:

p - process to destroy

objectImplementsMethod

public static boolean objectImplementsMethod(Object object,
                                             String methodName,
                                             Class[] parameters)

Determines if a given object implements a method given the name and the array of input parameters. Note that this doesn't quite check the method signature since the method return type is not checked.

Parameters:

object - to determine if it implements a method

methodName - name of the method

parameters - array of parameters

Returns:

if the object implements a method with the given name and class parameters

initApp

public static void initApp(Class applicationSubclass,
                           String[] args)

Initializes your WOApplication programmatically (for use in test cases and main methods) with the assumption that the current directory is your main bundle URL.

Parameters:

applicationSubclass - your Application subclass

args - the commandline arguments for your application

initApp

public static void initApp(String mainBundleName,
                           Class applicationSubclass,
                           String[] args)

Initializes your WOApplication programmatically (for use in test cases and main methods).

Parameters:

mainBundleName - the name of your main bundle

applicationSubclass - your Application subclass

args - the commandline arguments for your application

initApp

public static void initApp(String mainBundleName,
                           URL mainBundleURL,
                           Class applicationSubclass,
                           String[] args)

Initializes your WOApplication programmatically (for use in test cases and main methods).

Parameters:

mainBundleName - the name of your main bundle (or null to use mainBundleURL)

mainBundleURL - the URL to your main bundle (ignored if mainBundleName is set)

applicationSubclass - your Application subclass

args - the commandline arguments for your application

initEOF

public static void initEOF(String[] args)

Initializes Wonder EOF programmatically (for use in test cases and main methods). You do not need to call this method if you already called initApp. This is lighter-weight than initApp, and tries to just get enough configured to make EOF work properly. This method assumes you are running your app from a .woa folder.

This is equivalent to calling initEOF(new File("."), args).

Parameters:

args - the commandline arguments for your application

Throws:

IllegalArgumentException - if the current dir or mainBundleFolder is not a *.woa bundle.

initEOF

public static void initEOF(File mainBundleFolder,
                           String[] args)

Initializes Wonder EOF programmatically (for use in test cases and main methods). You do not need to call this method if you already called initApp. This is lighter-weight than initApp, and tries to just get enough configured to make EOF work properly.

This is equivalent to calling initEOF(mainBundleFolder, args, true, true, true).

Parameters:

mainBundleFolder - the folder of your main bundle

args - the commandline arguments for your application

Throws:

IllegalArgumentException - if the current dir or mainBundleFolder is not a *.woa bundle.

initEOF

public static void initEOF(File mainBundleFile,
                           String[] args,
                           boolean assertsBundleExists)

Initializes Wonder EOF programmatically (for use in test cases and main methods). You do not need to call this method if you already called initApp. This is lighter-weight than initApp, and tries to just get enough configured to make EOF work properly. This method is also, unlike initEOF(String[]) or initEOF(File, String[]), not so restrictive as to require the name of the bundle be a *.woa, and nor does it require *.framework as the name of the bundle.

It can therefore be useful for, and used with, folder, jar or war bundles -- whichever bundle is referenced by mainBundleURI -- so long as it is bundle-like in content rather than by name. For NSBundle, this usually just requires a Resources folder within the bundle.

For example, if you're build tool compiles sources and puts Resources under target/classes you can call this method via ERXExtensions.initEOF(new File(projectDir, "target/classes"), args, true).

Note 1: this will set the system property webobjects.user.dir to the canonical path of the given bundle uri if, and only if, the bundle uri points to a directory and is schema is file.

Note 2: this will set NSBundle's mainBundle to the referenced bundle loaded via ERXRuntimeUtilities.loadBundleIfNeeded(File) if found.

This is equivalent to calling initEOF(mainBundleFolder, args, assertsBundleExists, false, true).

Parameters:

mainBundleFile - the archive file or directory of your main bundle

args - the commandline arguments for your application

assertsBundleExists - ensures that the bundle exists and is loaded

Throws:

NSForwardException - if the given bundle doesn't satisfy the given assertions or ERXRuntimeUtilities.loadBundleIfNeeded or ERXApplication.setup fails.

See Also:

initEOF(File, String[], boolean, boolean, boolean)

initEOF

public static void initEOF(File mainBundleFile,
                           String[] args,
                           boolean assertsBundleExists,
                           boolean assertsBundleIsWOApplicationFolder,
                           boolean fallbackToUserDirAsBundle)

Initializes Wonder EOF programmatically (for use in test cases and main methods). You do not need to call this method if you already called initApp. This is lighter-weight than initApp, and tries to just get enough configured to make EOF work properly. This method is also, unlike initEOF(String[]) or initEOF(File, String[]), not so restrictive as to require the name of the bundle be a *.woa, and nor does it require *.framework as the name of the bundle.

It can therefore be useful for, and used with, folder, jar or war bundles -- whichever bundle is referenced by mainBundleURI -- so long as it is bundle-like in content rather than by name. For NSBundle, this usually just requires a Resources folder within the bundle.

For example, if you're build tool compiles sources and puts Resources under target/classes you can call this method via ERXExtensions.initEOF(new File(projectDir, "target/classes").toURI(), args).

Note 1: this will set the system property webobjects.user.dir to the canonical path of the given bundle uri if, and only if, the bundle uri points to a directory and is schema is file.

Note 2: this will set NSBundle's mainBundle to the referenced bundle loaded via ERXRuntimeUtilities.loadBundleIfNeeded(File) if found.

Parameters:

mainBundleFile - the archive file or directory of your main bundle

args - the commandline arguments for your application

assertsBundleExists - ensures that the bundle exists and is loaded

assertsBundleIsWOApplicationFolder - ensures that the bundle referenced by mainBundleFile, or the current dir if fallbackToUserDirAsBundle is true, is a *.woa bundle folder.

fallbackToUserDirAsBundle - falls back to current dir if the mainBundleFile does not exist

Throws:

NSForwardException - if the given bundle doesn't satisfy the given assertions or ERXRuntimeUtilities.loadBundleIfNeeded or ERXApplication.setup fails.

See Also:

ERXRuntimeUtilities.loadBundleIfNeeded(File), NSBundle._setMainBundle(NSBundle), ERXApplication.setup(String[]), bundleDidLoad(NSNotification)