Package wt.util

Class WTContext

java.lang.Object
java.util.Dictionary<Object,Object>
java.util.Hashtable<Object,Object>
wt.util.WTContext
All Implemented Interfaces:
Serializable, Cloneable, Map<Object,Object>
public final class WTContext extends Hashtable<Object,Object>
This class holds static state partitioned by applet or application instance. It is a specialized Hashtable for accessing static state via thread groups which correspond to applet or application instances.

This class is useful when there is a need for semi-global static state partitioned by applet or application. Using Java static fields is insufficient for this purpose since a class loaded from the local class path will share static state among applets from all codebases, and even classes loaded from a remote codebase may share static state between multiple applets from that codebase.

During applet initialization or application startup, a call to WTContext.init associates the calling thread group to a WTContext object and stores associated application arguments or the applet instance as part of the context. Later, static access is provided by looking up the applicable WTContext object according to the current thread's thread group.

This class implements the AppletStub and AppletContext interfaces to provide uniform access to these methods in the context of both applications and applets. It also enables applets to be treated as reusable components by allowing a parent applet or application context to be used as the stub for a new child applet instance.

This class includes applet start, stop, and destroy methods which can be used to invoke the corresponding methods on all registered listeners. applets should use these methods so that any child applets or frames that are registered as listeners can respond to these methods accordingly.

Since untrusted applets cannot set a default locale, this class also has convenience methods for setting and retrieving a Locale object associated with a WTContext object. Applets that wish to use a non-default locale should call setLocale with the desired Locale object, and any code that wishes to use this non-default locale can call getLocale to retrieve the locale that applies to their context. Likewise, similar methods are available to associate a timezone with a context.

This class also has convenience methods for loading class files and opening class resource files using the applicable applet class loader and URL connections. These methods should be used when classes which may have been loaded from the local classpath need to dynamically load additional classes or open resource files which may not reside in the local class path. For example, if core classes are deployed in the local class path, but an applet class is loaded from a Web server, any calls to Class.forName in the locally loaded classes will not find classes or files associated with the applet that do not also exist in the local class path.

Some Windchill classes perform static class initialization based on local properties obtained from the WTProperties class. Therefore, the WTContext.init method will implicitly call WTProperties.getLocalProperties to guarantee that the local properties will be available. If not, an ExceptionInInitializerError is thrown to abort application or applet startup. This is a safety measure since it is unlikely that static class initialization errors will be handled gracefully later on.

Example application main: 

 public static void main (String args)
 {
    // Initialize WTContext with command line arguments
    WTContext.init(args);

    // Do application stuff
    ...
 }
Example applet init: 
public void init ()
 {
    // Initialize WTContext for this applet
    WTContext.init(this);

    // Do applet init stuff
    ...
 }

 public void destroy ()
 {
    // Destroy WTContext for this applet
    WTContext.getContext(this).destroy(this);
 }
If context sensitive operations are performed from a thread group that does not map to an initialized context, it may be necessary to temporarily force mapping of the current thread to the desired context's thread group. The setContext and setContextGroup methods exist for this purpose.

In Microsoft's Internet Explorer browser, Java's AWT event dispatching may take place in a thread group that is shared by multiple applet contexts. The following example illustrates explicitly setting context in a actionPerformed method: 

 public void actionPerformed (ActionEvent e)
 {
    try
    {
       // Set context to parent applet while processing*       WTContext.setContext(applet);

       // Do action stuff
       ...
    }
    finally
    {
       WTContext.setContext((applet)null);
    }
 }
If not explicitly set, context lookup will fail over to any context corresponding to a child thread group of the current group. If none is found, a new empty context is implicitly created. This failover behavior is intended for fault tolerance in single-user applications or web browsers. It can be explicitly controlled in multi-user applications using the setLookupTolerance method.

NOTE: For performance of context lookup, nested context's are not supported. Stand alone applications usually have a single context, and applets should have one context per applet thread group created by the browser. If an application wants to manage multiple contexts for different thread groups, the application initialization methods should be called with a null argument array rather than calling the application initialization method with command line arguments. This is because the application initialization method creates a context that applies to the highest parent thread group reachable when it is called with the command line arguments. If an application starts out with a single context, but later wishes to transform into a container of multiple contexts, the initial context should be destroyed to break this high level thread group association.

Supported API: true
Extendable false

See Also:

  • Method Details

    • init

      public static void init(String[] args)
      Initialize WTContext for an application. Associates a context having the given argument array with the top-most parent thread group of the current thread group.

      Supported API: true
      Parameters:
      args - the args array passed to the application's main method.

    • init

      public static void init(String[] args, boolean local_resources_only)
      Initialize WTContext for a server application. Associates a context having the given argument array with the top-most parent thread group of the current thread group. If local_resources_only is true, this is a server application for which server resources are available as local (class path) resources. Server resources for a context are otherwise accessed using URLs relative to the server codebase as determined by the wt.util.WTProperties class.

      Supported API: true
      Parameters:
      args - the args array passed to the applicaion's main method.
      local_resources_only - use local resources as server resources
      See Also:

    • destroy

      public void destroy()
      Destroy this WTContext object. This should be called to guarantee timely garbage collection of objects referenced by the WTContext object. If not called, the objects will remain referenced until a new WTContext object is created, at which time the WTContext class will automatically destroy contexts associated with destroyed thread groups.

      Any registered AppletListener objects will be informed about of this destroy call.

      Applets should call the version of this method that accepts an Applet argument to guarantee that this context is only destroyed if the Applet object is the parent Applet for this context.

      Supported API: true

      See Also:

    • getContext

      public static WTContext getContext()
      Get the WTContext object associated with the current thread group. If no association has been created by an explicit call to init or setContext, then an empty context is created.

      Supported API: true
      Returns:
      the current WTContext object
      See Also:

    • getContext

      public static WTContext getContext(ThreadGroup group)
      Get the WTContext object currently associated with the given thread group. If no context exists for the given thread group, an empty context is created.

      Supported API: true
      Returns:
      the WTContext object
      See Also:

    • findContext

      public static WTContext findContext()
      Find the WTContext object currently associated with the current thread group.

      Supported API: true
      Returns:
      the current WTContext object or null if none
      See Also:

    • findContext

      public static WTContext findContext(ThreadGroup group)
      Find the WTContext object currently associated with the given thread group.

      Supported API: true
      Parameters:
      group - the thread group
      Returns:
      the current WTContext object or null if none
      See Also:

    • getContext

      public static WTContext getContext(Component component)
      Get the WTContext object currently associated with the given component's top-most parent applet. If the given component does not have a parent applet or if no context is currently associated with the applet, the current thread group's context is returned.

      Supported API: true
      Parameters:
      component - the Component object
      Returns:
      the WTContext object
      See Also:

    • setContextGroup

      public static void setContextGroup(ThreadGroup group)
      Temporarily set the WTContext object associated with the current thread to the one associated with the given thread group.

      This method can be used by an application which explicitly manages thread groups with different contexts. It should be used in a try/finally block to reset the association to the previous value or null when processing is complete.

      Supported API: true

      Parameters:
      group - the ThreadGroup object
      See Also:

    • getContextGroup

      public static ThreadGroup getContextGroup()
      Return WTContext thread group associated with the current thread. Returns null if no explicit association has been set using setContextGroup.

      Supported API: true
      Returns:
      the current mapping or null if none
      See Also:

    • getArgs

      public String[] getArgs()
      Get the argument array for this context. Returns the argument array that was specified when init was called for this context. If no argument array was specified, or it was null, an empty array is returned. This allows the return to be treated just like the argument array passed to an application's main method, which is never null.

      Supported API: true
      Returns:
      the argument array
      See Also:

    • setParentFrame

      public void setParentFrame(Frame parent_frame)
      Set the parent frame for this context.

      Supported API: true
      See Also:

    • getThreadGroup

      public ThreadGroup getThreadGroup()
      Get the thread group corresponding to this context. Returns the ThreadGroup associated with this context when it was initialized.

      Supported API: true
      Returns:
      the ThreadGroup object
      See Also:

    • currentThreadGroup

      public static ThreadGroup currentThreadGroup()
      Get the current thread group of the calling thread. First checks to see if the currentThread has been mapped to a specific thread group and if so returns the mapped thread group. This mapping occurs through calls to setContext or setContextGroup. Otherwise, if a security manager is present, it is called to get the thread group into which any new thread being constructed in this thread would be assigned. By default, it returns the thread group of the current thread, but this could be overriden by specific security manager to return the appropriate thread group if called from within a system thread. If no security manager is present, the current thread's thread group is returned.

      Supported API: true
      Returns:
      the ThreadGroup object

    • setVerbose

      public static void setVerbose(boolean verbose)
      Set verbose mode for debugging. When true, this class will display trace messages when contexts are created or destroyed and when resources are being loaded via the WTContext class.

      Supported API: true
      Parameters:
      verbose - the verbose setting

    • interrupt

      public void interrupt()
      Interrupt all active threads in this context's thread group and its subgroups. The calling thread, if included, is not interrupted.

      Note: a bug in JDK 1.1 prevents applications from terminating properly if their main thread is interrupted, even after the run method has returned. Therefore, all threads named "main" are also skipped.

      Supported API: true

    • useLocalResourcesOnly

      public boolean useLocalResourcesOnly()
      Return whether local resources should be used as server resources for this context.

      Supported API: true
      Returns:
      the local_resources_only flag used on the init method.

    • setLenientLookup

      public static void setLenientLookup(boolean lenient)
      Set whether context lookup should be lenient with respect to context initialization. When true (default), lookup for a thread group that does not correspond to an initialized context will fail over to any context initialized for a child thread group. Applications managing multiple contexts for different users may wish to disable this fault tolerance since it may lead to unexpected context sharing. Implicit creation of contexts is still allowed, but only if there is no context already initialized for a child thread group (which would result in nested contexts, which are not allowed).

      Supported API: true
      Parameters:
      lenient -

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener listener)
      Add a PropertyChangeListener to the listener list. Property change events will be fired to all registered listeners whenever a value in this hashtable is added, changed, or removed.

      Supported API: true
      Parameters:
      listener - the PropertyChangeListener to be added

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener listener)
      Remove a PropertyChangeListener from the listener list.

      Supported API: true
      Parameters:
      listener - the PropertyChangeListener to be removed

    • put

      public Object put(Object key, Object value)
      Override Hashtable.put to add property change support.

      Supported API: true
      Specified by:
      put in interface Map<Object,Object>
      Overrides:
      put in class Hashtable<Object,Object>
      Parameters:
      key - the hashtable key
      value - the value
      Returns:
      the previous value of the specified key in this hashtable, or null if it did not have one.
      See Also:

    • remove

      public Object remove(Object key)
      Override Hashtable.remove to add property change support.

      Supported API: true
      Specified by:
      remove in interface Map<Object,Object>
      Overrides:
      remove in class Hashtable<Object,Object>
      Parameters:
      key - the key that needs to be removed
      Returns:
      the value to which the key had been mapped in this hashtable, or null if the key did not have a mapping.
      See Also:

    • addAppletListener

      public void addAppletListener(AppletListener listener)
      Add a AppletListener to the listener list.

      Supported API: true
      Parameters:
      listener - the AppletListener to be added

    • addGlobalAppletListener

      public static void addGlobalAppletListener(AppletListener listener)
      Add a global AppletListener to the listener list. Global listeners will receive AppletListener calls for all contexts. Application code may issue a WTContext.stop() to signal a panic shutdown. This method allows adding a single listener within applications that may have multiple multi contexts active simultaneously.

      Supported API: true
      Parameters:
      listener - the AppletListener to be added

    • stop

      public void stop()
      Report a Applet.stop call to any registered listeners.

      Supported API: true

    • getCodeBase

      public URL getCodeBase()
      Gets the base URL.

      Supported API: true
      Returns:
      the URL of the applet.

    • getParameter

      public String getParameter(String name)
      Returns the value of the named parameter in the HTML tag. For example, if an applet is specified as
        <applet code="Clock" width=50 height=50>
        <param name=Color value="blue">
        </applet>

      then a call to getParameter("Color") returns the value "blue".

      Supported API: true

      Parameters:
      name - a parameter name.
      Returns:
      the value of the named parameter.

    • getImage

      public Image getImage(URL url)
      Returns an Image object that can then be painted on the screen. The url argument that is passed as an argument must specify an absolute URL.

      This method always returns immediately, whether or not the image exists. When the applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

      Supported API: true

      Parameters:
      url - an absolute URL giving the location of the image.
      Returns:
      the image at the specified URL.
      See Also:

    • getImage

      public Image getImage(String name)
      Get an image from a resource file. For resources with corresponding HTTP or FILE URLs, the normal getImage method is called. For system resources, the resource is loaded into a byte array and converted to an image from there. This is due to problems Netscape and Microsoft VMs have dealing with system resource URLs.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      Returns:
      the image
      See Also:

    • showDocument

      public void showDocument(URL url)
      Replaces the Web page currently being viewed with the given URL. If this context has an applet, it is passed to the applet context's showDocument method. If this context is an application and can execute commands, an attempt is made to launch a browser to view the page. On Windows platforms this is done using rundll32.exe to open the URL in the user's default browser. On unix, this is done by trying to execute netscape. To allow the commands to be configured, a property named wt.context.showDocument.<os_name> can be set where os_name is the value of the os.name Java system property with any space characters replaced by underscore. The value is a MessageFormat pattern where "{0}" will be replaced by the URL. If the value contains more than one command separated by newline, each line is executed until one finishes without writing anything to stderr.

      Supported API: true
      Parameters:
      url - an absolute URL giving the location of the document.

    • showDocument

      public void showDocument(URL url, String target)
      Requests that the browser or applet viewer show the Web page indicated by the url argument. The target argument indicates where to display the frame. The target argument is interpreted as follows:

      "_self" show in the current frame
      "_parent"show in the parent frame
      "_top" show in the topmost frame
      "_blank" show in a new unnamed top-level window
      nameshow in a new top-level window named name

      An applet viewer or browser is free to ignore showDocument.

      Supported API: true

      Parameters:
      url - an absolute URL giving the location of the document.
      target - a String indicating where to display the page.

    • setLocale

      public void setLocale(Locale locale)
      Set locale for this context. Setting to null returns the locale to the default returned by Locale.getDefault. If this context corresponds to an applet, the applet's locale is set so it can affect the getLocale method of components contained in the applet.

      Supported API: true
      Parameters:
      locale - the Locale object

    • getLocale

      public Locale getLocale()
      Get locale for this context. If locale has not been explicitly set using setLocale, the locale defined by a parameter named wt.context.locale is returned. If this parameter is not set, then the default locale returned by the context's applet or by Locale.getDefault is returned.

      Supported API: true
      Returns:
      the Locale object

    • setTimeZone

      public void setTimeZone(TimeZone timezone)
      Set time zone for this context. Setting to null returns the time zone to the default.

      Supported API: true
      Parameters:
      timezone - the TimeZone object

    • setDefaultTimeZone

      public static void setDefaultTimeZone(TimeZone timezone)
      Set default time zone. Setting to null returns the time zone to the default returned by TimeZone.getDefault.

      Supported API: true
      Parameters:
      timezone - the TimeZone object

    • getTimeZone

      public TimeZone getTimeZone()
      Get time zone for this context. If time zone has not been explicitly set using setTimeZone, the default time zone is returned.

      Supported API: true
      Returns:
      the TimeZone object

    • getClassLoader

      public ClassLoader getClassLoader()
      Returns the Class loader of this context's top-most applet.

      Supported API: true

    • loadClass

      public Class loadClass(String name) throws ClassNotFoundException
      Returns the Class object associated with the class with the given string name. Given the fully-qualified name for a class or interface, this method attempts to locate, load and link the class. This method delegates to the class loader of this context's top-most applet.

      Supported API: true
      Throws:
      ClassNotFoundException - if context's class loader can't find the class file

    • getSystemResourceAsStream

      public InputStream getSystemResourceAsStream(String name)
      Get an InputStream for a given system resource name. This is similar to ClassLoader.getSystemResourceAsStream but attempts to work around Netscape security exceptions. Returns null if no resource by this name is found. The returned InputStream is buffered if necessary for reading efficiency.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      url - a single element URL array to receive the URL corresponding to the stream
      Returns:
      an InputStream for the resource, or null if not found

    • getResourceAsStream

      public InputStream getResourceAsStream(String name)
      Get an InputStream for a given resource name. If the WTContext class was loaded from the local class path, this method first attempts to open the resource as a local system resource. If not found, or unable to access local resources due to security restrictions, this method delegates to the class loader of this context's top-most applet. If that class loader is unable to open the resource, a URL connection is attempted relative to this context's codebase. Null is returned if no resource by this name is found. The returned InputStream is buffered if necessary for reading efficiency.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      Returns:
      an InputStream for the resource, or null if not found

    • getResourceAsStream

      public InputStream getResourceAsStream(String name, URL[] url)
      Get an InputStream for a given resource name. If the WTContext class was loaded from the local class path, this method first attempts to open the resource as a local system resource. If not found, or unable to access local resources due to security restrictions, this method delegates to the class loader of this context's top-most applet. If that class loader is unable to open the resource, a URL connection is attempted relative to this context's codebase. Null is returned if no resource by this name is found. The returned InputStream is buffered if necessary for reading efficiency.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      url - a single element URL array to receive the URL corresponding to the stream
      Returns:
      an InputStream for the resource, or null if not found

    • getResourceAsStream

      public InputStream getResourceAsStream(Class cls, String name)
      Get an InputStream for a given resource name after applying a naming convention based on the supplied class name: if the resource name starts with "/", it is used as is. Otherwise, the name of the class's package is prepended, after converting "." to "/". This method first attempts to open the resource as a local system resource. If not found, or unable to access local resources due to security restrictions, this method delegates to the class loader of this context's top-most applet. If that class loader is unable to open the resource, a URL connection is attempted relative to this context's codebase. Null is returned if no resource by this name is found. The returned InputStream is buffered if necessary for reading efficiency.

      Supported API: true
      Parameters:
      cls - the class to fully qualify relative resource names
      name - the name of the resource (full path, may include leading "/")
      Returns:
      an InputStream for the resource, or null if not found

    • getResourceAsStream

      public InputStream getResourceAsStream(URL codebase, String name) throws IOException
      Get an InputStream for a given resource name by opening a URL connection relative to the given codebase. The returned InputStream is buffered if necessary for reading efficiency.

      Note that if useLocalResourcesOnly() returns true and the codebase result is identical to getCodebase(), then getResourceAsStream(java.lang.String) is used instead where possible. Note that callers that know they are doing this should simply call getResourceAsStream(java.lang.String) instead -- the presence of this logic in this method is really a workaround for errant callers.

      Supported API: true

      Parameters:
      codebase - the codebase URL
      name - the name of the resource (full path, may include leading "/")
      Returns:
      an InputStream for the resource, or null if not found
      Throws:
      IOException

    • getResource

      public URL getResource(String name)
      Find a resource with a given a name. The return is a URL to the resource. Doing a getContent() on the URL may return an Image, an AudioClip, or an InputStream. The method delegates to the class loader of this context's top-most applet. If that class loader is unable to open the resource, a URL is built relative to this context's codebase.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      Returns:
      a URL for the resource

    • getResource

      public URL getResource(URL codebase, String name)
      Find a resource with a given a name. The return is a URL to the resource. This method builds a URL relative to a given codebase URL.

      Supported API: true
      Parameters:
      codebase - the codebase URL
      name - the name of the resource (full path, may include leading "/")
      Returns:
      a URL for the resource

    • getServerResourceAsStream

      public InputStream getServerResourceAsStream(String name)
      Get an InputStream for a given server resource name by opening a URL connection relative to this context's codebase. This is similar to getResourceAsStream but won't find resources in the local class path. The returned InputStream is buffered if necessary for reading efficiency.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      Returns:
      an InputStream for the resource, or null if not found

    • getServerResource

      public URL getServerResource(String name)
      Find a server resource with a given name. The return is a URL to the resource. This method builds a URL relative to this context's server codebase. This is similar to getResource but doesn't return URLs to local class path resources.

      Supported API: true
      Parameters:
      name - the name of the resource (full path, may include leading "/")
      Returns:
      a URL for the resource

    • getSystemClipboard

      public Clipboard getSystemClipboard()
      Get the system clipboard.

      Supported API: true
      Returns:
      the system clipboard.