com.jgoodies.uif.application
Class ApplicationContext

java.lang.Object
  extended by com.jgoodies.binding.beans.Model
      extended by com.jgoodies.uif.application.ApplicationContext
All Implemented Interfaces:
com.jgoodies.binding.beans.Observable, Serializable

public final class ApplicationContext
extends com.jgoodies.binding.beans.Model

Provides shared access for Swing application data. Addresses the following topics:

TODO: Consider re-reading action values to enable users to switch the Locale and update action views automatically. The current code just invalidates the ActionMap cache and requires to rebuild the UI.

Version:
$Revision: 1.14 $
Author:
Karsten Lentzsch
See Also:
Serialized Form

Method Summary
 void clearActionMap(Object target)
          Clears the ActionMap cache entry for the given target.
protected  ResourceMap createApplicationResourceMap()
          Creates and returns the application-level ResourceMap.
static Action getAction(Object target, String actionName)
          Deprecated. Replaced by Application.getAction(Object, String)
 ActionMap getActionMap(Object target)
          Looks up and returns the ActionMap for the given target.
 ActionMap getActionMap(Object target, ResourceMap resourceMap)
          Looks up and returns the ActionMap for the given target.
 Application getApplication()
          Returns this context's Application.
 Class<? extends Application> getApplicationClass()
          Returns the class of this context's application.
protected  String getApplicationPreferencesNodeName()
          Returns the preferences path name for this application.
static ApplicationContext getInstance()
          Lazily creates and returns the single instance of this application context.
 ResourceMap getResourceMap()
          Lazily creates and returns the application-level ResourceMap.
 ResourceMap getResourceMap(Class<?> type)
          Looks up and returns a ResourceMap for the given class.
 Preferences getSystemPreferences()
          Returns this application's root preference node for the system.
 Preferences getUserPreferences()
          Returns this application's root preference node for the calling user.
 
Methods inherited from class com.jgoodies.binding.beans.Model
addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, equals, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, fireMultiplePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static ApplicationContext getInstance()
Lazily creates and returns the single instance of this application context.

Returns:
the single instance

getApplicationClass

public Class<? extends Application> getApplicationClass()
Returns the class of this context's application. Used by the resource management to look up bundles that are related to the application class.

Returns:
the class of this context's application

getApplication

public Application getApplication()
Returns this context's Application.

Returns:
this context's Application

getResourceMap

public ResourceMap getResourceMap()
Lazily creates and returns the application-level ResourceMap. An Application mypackage.MyApplication must provide a resource bundle named mypackage.MyApplication.resources.MyApplication.

Returns:
the application-wide ResourceMap

getResourceMap

public ResourceMap getResourceMap(Class<?> type)
Looks up and returns a ResourceMap for the given class. It looks for a class-level, package-level and application-level ResourceBundle to build a hierarchy of ResourceMaps. This hierarchy is used for a fallback mechanism during the ResourceMap resource lookup.

The class-level and package-level ResourceBundles are optional, the application-level bundle is mandatory. The application-level ResourceMap is the parent of all package-level ResourceMaps. A package-level ResourceMap - if any - is the parent of the class-level ResourceMaps for all classes in that package. If the package-level bundle is absent, the application-wide ResourceMap is used as direct parent for the class-level ResourceMap - if any.

For class mypackage.MyClass and Application apppackage.MyApplication the following resource bundles are searched to build ResourceMaps: mypackage.resources.MyClass (optional class-level), mypackage.resources.Package (optional package-level), apppackage.resources.MyApplication (mandatory application-level).

When looking for a resource, the ResourceMap first uses its own ResourceBundle. In case the resource is missing there, the lookup continues with the ResourceMap's parent ResourceMap. A resource lookup fails, if all ResourceMaps in this path miss the resource.

Parameters:
type - a class to lookup resources for
Returns:
the type's package resource map - if available and type is not null, otherwise this application's resource map
See Also:
ResourceMap

createApplicationResourceMap

protected ResourceMap createApplicationResourceMap()
Creates and returns the application-level ResourceMap. This implementation creates a ResourceMap chain that starts with the launched Application class and stops at the Application class. Each resource maps parent is the resource map of its superclass.

If the application has not been launched, this methods returns the resource map for Application.class.

Subclasses may override this method to set a parent ResourceMap that is shared by multiple applications.

Returns:
the application-level ResourceMap chain

getAction

@Deprecated
public static Action getAction(Object target,
                                          String actionName)
Deprecated. Replaced by Application.getAction(Object, String)

Returns the action named actionName of the given target object. This a convenience method for ApplicationContext.getInstance().getActionMap(target).get(actionName).

Note: Requesting an Action will create a hard reference to the given target, so it cannot be cleared by the garbage collector until the ActionMap entry is cleared using clearActionMap(Object).

Parameters:
target - the instance that will perform the Action
actionName - used to look up the associated Action method
Returns:
the Action for name actionName of the given target.
Throws:
IllegalArgumentException - if the action is absent.

getActionMap

public ActionMap getActionMap(Object target)
Looks up and returns the ActionMap for the given target. This map contains Actions for the target's method that are annotated with the @Action annotation.

The actions text, icon, description, etc. are initialized from the target's resource map. If you want to use a custom resource map, use getActionMap(Object, ResourceMap) instead.

Note: Requesting an ActionMap will create a hard reference to the given target, so it cannot be cleared by the garbage collector until the ActionMap entry is cleared using clearActionMap(Object).

Parameters:
target - the object that shall execute the Actions
Returns:
an ActionMap with Actions that perform the target's action methods.

getActionMap

public ActionMap getActionMap(Object target,
                              ResourceMap resourceMap)
Looks up and returns the ActionMap for the given target. This map contains Actions for the target's method that are annotated with the @Action annotation.

The actions text, icon, description, etc. are initialized from the given resource map. If you can use the target's resource map, use getActionMap(Object) instead.

Note: Requesting an ActionMap will create a hard reference to the given target, so it cannot be cleared by the garbage collector until the ActionMap entry is cleared using clearActionMap(Object).

Parameters:
target - the object that shall execute the Actions
resourceMap - used to initialize the action text, icon, etc
Returns:
an ActionMap with Actions that perform the target's action methods.

clearActionMap

public void clearActionMap(Object target)
Clears the ActionMap cache entry for the given target. Used to avoid memory leaks when the target isn't required anymore.

Parameters:
target - the key in the ActionMap cache
Throws:
NullPointerException - if target is null
Since:
1.9.1

getUserPreferences

public Preferences getUserPreferences()
Returns this application's root preference node for the calling user. Useful for information that is specific to a user and an application. User-specific data that shall be shared between applications should use Preferences.userRoot() instead.

For example the user preferences root of the Application class com.package1.MyApp uses the path <user-root>/<application-root> which is <user-root>/com/package1/MyApp by default.

Returns:
the user preference node associated with this application.
Throws:
SecurityException - if a security manager is present and it denies RuntimePermission("preferences").
See Also:
RuntimePermission, Preferences

getSystemPreferences

public Preferences getSystemPreferences()
Returns this application's root preference node for the system. Useful for information that is shared by all users but associated with an application. System data that shall be shared between applications should use Preferences.systemRoot() instead.

For example the system preferences root of the Application class com.package1.MyApp uses the path <system-root>/<application-root> which is <system-root>/com/package1/MyApp by default.

Returns:
the system preference node associated with this application.
Throws:
SecurityException - if a security manager is present and it denies RuntimePermission("preferences").
See Also:
RuntimePermission, Preferences

getApplicationPreferencesNodeName

protected String getApplicationPreferencesNodeName()
Returns the preferences path name for this application. For example the path name for com.mydomain.mypackage.MyApplication is "/com/mydomain/mypackage/MyApplication"

Subclasses may override to use a simpler name

Returns:
the preferences node name associated with this application


Copyright © 2000-2008 JGoodies Karsten Lentzsch. All Rights Reserved.