public final class

AppContext

extends Object
java.lang.Object
   ↳ sun.awt.AppContext

Class Overview

The AppContext is a table referenced by ThreadGroup which stores application service instances. (If you are not writing an application service, or don't know what one is, please do not use this class.) The AppContext allows applet access to what would otherwise be potentially dangerous services, such as the ability to peek at EventQueues or change the look-and-feel of a Swing application.

Most application services use a singleton object to provide their services, either as a default (such as getSystemEventQueue or getDefaultToolkit) or as static methods with class data (System). The AppContext works with the former method by extending the concept of "default" to be ThreadGroup-specific. Application services lookup their singleton in the AppContext.

For example, here we have a Foo service, with its pre-AppContext code:

    public class Foo {
        private static Foo defaultFoo = new Foo();

        public static Foo getDefaultFoo() {
            return defaultFoo;
        }

    ... Foo service methods
    }

The problem with the above is that the Foo service is global in scope, so that applets and other untrusted code can execute methods on the single, shared Foo instance. The Foo service therefore either needs to block its use by untrusted code using a SecurityManager test, or restrict its capabilities so that it doesn't matter if untrusted code executes it.

Here's the Foo class written to use the AppContext:

    public class Foo {
        public static Foo getDefaultFoo() {
            Foo foo = (Foo)AppContext.getAppContext().get(Foo.class);
            if (foo == null) {
                foo = new Foo();
                getAppContext().put(Foo.class, foo);
            }
            return foo;
        }

    ... Foo service methods
    }

Since a separate AppContext can exist for each ThreadGroup, trusted and untrusted code have access to different Foo instances. This allows untrusted code access to "system-wide" services -- the service remains within the AppContext "sandbox". For example, say a malicious applet wants to peek all of the key events on the EventQueue to listen for passwords; if separate EventQueues are used for each ThreadGroup using AppContexts, the only key events that applet will be able to listen to are its own. A more reasonable applet request would be to change the Swing default look-and-feel; with that default stored in an AppContext, the applet's look-and-feel will change without disrupting other applets or potentially the browser itself.

Because the AppContext is a facility for safely extending application service support to applets, none of its methods may be blocked by a a SecurityManager check in a valid Java implementation. Applets may therefore safely invoke any of its methods without worry of being blocked. Note: If a SecurityManager is installed which derives from sun.awt.AWTSecurityManager, it may override the AWTSecurityManager.getAppContext() method to return the proper AppContext based on the execution context, in the case where the default ThreadGroup-based AppContext indexing would return the main "system" AppContext. For example, in an applet situation, if a system thread calls into an applet, rather than returning the main "system" AppContext (the one corresponding to the system thread), an installed AWTSecurityManager may return the applet's AppContext based on the execution context.

Summary

Constants
String DISPOSED_PROPERTY_NAME
String GUI_DISPOSED
Fields
public static final Object EVENT_QUEUE_KEY
Public Methods
synchronized void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list for a specific property.
void dispose()
Disposes of this AppContext, all of its top-level Frames, and all Threads and ThreadGroups contained within it.
Object get(Object key)
Returns the value to which the specified key is mapped in this context.
final static AppContext getAppContext()
Returns the appropriate AppContext for the caller, as determined by its ThreadGroup.
static Set<AppContext> getAppContexts()
Returns a set containing all AppContexts.
ClassLoader getContextClassLoader()
Returns the context ClassLoader that was used to create this AppContext.
synchronized PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the property change listeners registered on this component.
synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
Returns an array of all the listeners which have been associated with the named property.
ThreadGroup getThreadGroup()
Returns the root ThreadGroup for all Threads contained within this AppContext.
boolean isDisposed()
Object put(Object key, Object value)
Maps the specified key to the specified value in this AppContext.
Object remove(Object key)
Removes the key (and its corresponding value) from this AppContext.
synchronized void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list for a specific property.
String toString()
Returns a string representation of this AppContext.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String DISPOSED_PROPERTY_NAME

Constant Value: "disposed"

public static final String GUI_DISPOSED

Constant Value: "guidisposed"

Fields

public static final Object EVENT_QUEUE_KEY

Public Methods

public synchronized void addPropertyChangeListener (String propertyName, PropertyChangeListener listener)

Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be one of the following:

  • if this AppContext is disposed ("disposed")
  • if this AppContext's unowned Windows have been disposed ("guidisposed"). Code to cleanup after the GUI is disposed (such as LookAndFeel.uninitialize()) should execute in response to this property being fired. Notifications for the "guidisposed" property are sent on the event dispatch thread.

If listener is null, no exception is thrown and no action is performed.

Parameters
propertyName one of the property names listed above
listener the PropertyChangeListener to be added

public void dispose ()

Disposes of this AppContext, all of its top-level Frames, and all Threads and ThreadGroups contained within it. This method must be called from a Thread which is not contained within this AppContext.

Throws
IllegalThreadStateException if the current thread is contained within this AppContext

public Object get (Object key)

Returns the value to which the specified key is mapped in this context.

Parameters
key a key in the AppContext.
Returns
  • the value to which the key is mapped in this AppContext; null if the key is not mapped to any value.

public static final AppContext getAppContext ()

Returns the appropriate AppContext for the caller, as determined by its ThreadGroup. If the main "system" AppContext would be returned and there's an AWTSecurityManager installed, it is called to get the proper AppContext based on the execution context.

Returns
  • the AppContext for the caller.
See Also

public static Set<AppContext> getAppContexts ()

Returns a set containing all AppContexts.

public ClassLoader getContextClassLoader ()

Returns the context ClassLoader that was used to create this AppContext.

public synchronized PropertyChangeListener[] getPropertyChangeListeners ()

Returns an array of all the property change listeners registered on this component.

Returns
  • all of this component's PropertyChangeListeners or an empty array if no property change listeners are currently registered

public synchronized PropertyChangeListener[] getPropertyChangeListeners (String propertyName)

Returns an array of all the listeners which have been associated with the named property.

Returns
  • all of the PropertyChangeListeners associated with the named property or an empty array if no listeners have been added

public ThreadGroup getThreadGroup ()

Returns the root ThreadGroup for all Threads contained within this AppContext.

public boolean isDisposed ()

public Object put (Object key, Object value)

Maps the specified key to the specified value in this AppContext. Neither the key nor the value can be null.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Parameters
key the AppContext key.
value the value.
Returns
  • the previous value of the specified key in this AppContext, or null if it did not have one.
Throws
NullPointerException if the key or value is null.
See Also

public Object remove (Object key)

Removes the key (and its corresponding value) from this AppContext. This method does nothing if the key is not in the AppContext.

Parameters
key the key that needs to be removed.
Returns
  • the value to which the key had been mapped in this AppContext, or null if the key did not have a mapping.

public synchronized void removePropertyChangeListener (String propertyName, PropertyChangeListener listener)

Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

If listener is null, no exception is thrown and no action is performed.

Parameters
propertyName a valid property name
listener the PropertyChangeListener to be removed

public String toString ()

Returns a string representation of this AppContext.

Returns
  • a string representation of the object.