Applicet Framework for Applets and Applications v2.03

be.arci.applet
Class JApplicet

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--java.applet.Applet
                          |
                          +--javax.swing.JApplet
                                |
                                +--be.arci.applet.JApplicet
All Implemented Interfaces:
javax.accessibility.Accessible, Framework, java.awt.image.ImageObserver, java.awt.MenuContainer, javax.swing.RootPaneContainer, java.io.Serializable

public class JApplicet
extends javax.swing.JApplet
implements Framework

Extends JApplet with full support for running as an application, with access to resource URLs and inputstreams, images, sound and all, and with carefully designed internationalization (I18N) conveniences that make internationalization of your applets and applications trivial.

Use JApplicet instead of JApplet as superclass of your applet, and immediately run as application with full functionality.

Note: For the AWT Applicet version, interface javax.accessibility.Accessible and inner classes java.applet.Applet.AccessibleApplet, java.awt.Panel.AccessibleAWTPanel, java.awt.Container.AccessibleAWTContainer and java.awt.Container.AccessibleAWTComponent are inherited from java.applet.Applet in Java 2 only, not in Java 1.x.

See Also:
runAsApplication, Applicet Framework overview, Serialized Form

Inner Class Summary
 class JApplicet.Context
          The execution environment for JApplicet applications (implementing the java.applet.AppletContext interface); also adds functionality, specific for JApplicet applications, that need not be distributed with JApplicet applets.
 
Inner classes inherited from class javax.swing.JApplet
javax.swing.JApplet.AccessibleJApplet
 
Inner classes inherited from class java.applet.Applet
java.applet.Applet.AccessibleApplet
 
Inner classes inherited from class java.awt.Panel
java.awt.Panel.AccessibleAWTPanel
 
Inner classes inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Inner classes inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent
 
Field Summary
static java.lang.String sCopy
          Copyright notice; none of the Applicet Framework license types allows you to change this.
 
Fields inherited from class javax.swing.JApplet
accessibleContext, rootPane, rootPaneCheckingEnabled
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
protected JApplicet()
          It makes no sense to use an JApplicet without subclassing; therefor the constructor is protected (unlike JApplet's constructor).
 
Method Summary
 javax.swing.JFrame createFrame()
          Creates a frame with the class name both as title and as base name for the icon filename: first ".gif" is appended to try and get an icon image, then ".jpg".
 java.lang.String formatI18NString(java.lang.String sPatternName, java.lang.Object[] aoArgs)
          Formats an array of Object arguments to a localized message according to the named pattern; the pattern name is used to look up both the localized pattern as well as localized argument Strings for those Object arguments that are null.
 java.lang.String formatI18NString(java.lang.String sPatternName, java.lang.String sDefaultPattern, java.lang.Object[] aoArgs)
          Formats an array of Object arguments to a localized message according to the named pattern; the pattern name is used to look up both the localized pattern as well as localized argument Strings for those Object arguments that are null.
 java.lang.String getAppletInfo()
          Returns information about this JApplicet; the default implementation returns the JApplicet copyright notice.
 java.applet.AudioClip getAudioClip(java.lang.String sName)
          Utitlity method that does a best effort to get the named AudioClip resource, depending on this JApplicet's resource context and execution environment.
 java.applet.AudioClip getAudioClip(java.lang.String sName, int iResourceContext)
          Gets the named AudioClip resource, either by reading it from the resource's URL or from an InputStream opened on the resource, depending on the iResourceContext parameter.
 java.awt.Frame getFrame()
          Convenience method that returns and always reuses the same JFrame, created by createFrame().
 I18NDelegate getI18NDelegate()
          Retrieves the I18NDelegate of this JApplicet, giving more control over I18N aspects.
 java.lang.String[][] getI18NParameterInfo(java.lang.String[][] aasDefaultParameterInfo, char cDelimiter)
          Retrieves localized parameterinfo based on a default array of parameterinfo Strings.
 java.lang.String getI18NString(java.lang.String sName)
          Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet.
 java.lang.String getI18NString(java.lang.String sName, java.lang.String sDefault)
          Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet.
 java.lang.String[] getI18NStringArray(java.lang.String sName, char cDelimiter)
          Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet, and splits it into an array of Strings using the delimiter character.
 java.lang.String[] getI18NStringArray(java.lang.String sName, java.lang.String sDefault, char cDelimiter)
          Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet, and splits it into an array of Strings using the delimiter character.
 java.awt.Image getImage(java.lang.String sName)
          Utitlity method that does a best effort to get the named Image resource, depending on this JApplicet's resource context and execution environment.
 java.awt.Image getImage(java.lang.String sName, int iResourceContext)
          Gets the named Image resource, either by reading it from the resource's URL or from an InputStream opened on the resource, depending on the iResourceContext parameter.
 java.util.Locale getLocale()
          Gets the Locale for the JApplicet, if it has been set, or else the default Locale of the execution environment.
 java.lang.String getParameter(java.lang.String sName, java.lang.String sDefaultValue)
          Convenience method to retrieve a named parameter, with fallback to a default value.
 java.awt.Frame getParentFrame()
          Returns the first parent of this JApplicet that is a Frame (using Component.getParent() to get there).
 java.awt.Dimension getPreferredSize()
          The return value of this method is used to set the size of an JApplicet application.
protected  java.lang.String[][] getReservedParameterInfo()
          Returns information about the reserved parameters that are understood by an JApplicet application.
 java.net.URL getResource(java.lang.String sName)
          Returns the URL for a resource with a given name, according to the resource context for this JApplicet.
 java.net.URL getResource(java.lang.String sName, int iResourceContext)
          Returns the URL for a resource with a given name, according to the specified resource context.
 java.io.InputStream getResourceAsStream(java.lang.String sName)
          Returns an InputStream on a resource with a given name, according to the resource context for this JApplicet, or null if no such resource is found.
 java.io.InputStream getResourceAsStream(java.lang.String sName, int iResourceContext)
          Returns an InputStream on a resource with a given name, according to the specified resource context, or null if no such resource is found.
 int getResourceContext()
          Returns the context for finding Resources.
static java.lang.String[] getStringArray(java.lang.String sArray, char cDelimiter)
          Convenience method to split a String into an array of Strings using a delimiter character.
protected  java.lang.String getUsage()
          Convenience method to return a 'typical use' message for display in the usage dialog of an JApplicet application.
 boolean isApplication()
          You might want to do something extra when running as application.
static boolean isNetscapeVM()
          Returns true if the JApplicet runs under a Netscape VM.
 void play(java.lang.String sName)
          Utitlity method that does a best effort to play the named AudioClip resource, depending on this JApplicet's resource context and execution environment.
 void play(java.lang.String sName, int iResourceContext)
          Plays the named AudioClip resource, either by reading it from the resource's URL or from an InputStream opened on the resource, depending on the iResourceContext parameter.
 byte[] readResource(java.io.InputStream is)
          Reads an InputStream (typically obtained as the return value of invoking getResourceAsStream) to end into a byte[].
 JApplicet runAsApplication(java.lang.String[] args)
          Brings up a JFrame containing the JApplicet application, and the JApplicet is initted and started.
 JApplicet runAsApplication(java.lang.String[] args, boolean swSetActive)
          Creates a JFrame containing the JApplicet application.
 JApplicet runAsApplication(java.lang.String[] args, boolean swSetActive, boolean swCreateFrame, java.lang.String sName)
          Creates an application AppletStub and AppletContext for the JApplicet application.
 void setResourceContext(int iResourceContext)
          Sets the context for finding Resources.
 
Methods inherited from class javax.swing.JApplet
addImpl, createRootPane, getAccessibleContext, getContentPane, getGlassPane, getJMenuBar, getLayeredPane, getRootPane, isRootPaneCheckingEnabled, paramString, processKeyEvent, remove, setContentPane, setGlassPane, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, update
 
Methods inherited from class java.applet.Applet
destroy, getAppletContext, getAudioClip, getAudioClip, getCodeBase, getDocumentBase, getImage, getImage, getParameter, getParameterInfo, init, isActive, newAudioClip, play, play, resize, resize, setStub, showStatus, start, stop
 
Methods inherited from class java.awt.Panel
addNotify
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, removeNotify, setFont, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getInputContext, getInputMethodRequests, getLocation, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface be.arci.applet.Framework
showStatus
 

Field Detail

sCopy

public static final java.lang.String sCopy
Copyright notice; none of the Applicet Framework license types allows you to change this.
Constructor Detail

JApplicet

protected JApplicet()
It makes no sense to use an JApplicet without subclassing; therefor the constructor is protected (unlike JApplet's constructor).
Method Detail

isNetscapeVM

public static boolean isNetscapeVM()
Returns true if the JApplicet runs under a Netscape VM.

Netscape 4.0x does not support the Class.getResource() and Class.getSystemResource() methods, (see http://developer.netscape.com/docs/technote/java/getresource/getresource.html) so depending on the result of isNetscapeVM() you might have to call Class.getResourceAsStream() and Class.getSystemResourceAsStream() instead.

NOTE:
For most cases, you can just rely on JApplicet's plain handling-resources-by-name methods without worrying about Netscape or anything else.

Returns:
true if this JApplicet is running in a Netscape VM.
See Also:
getResource, getResourceAsStream, getAudioClip, play, getImage

getStringArray

public static java.lang.String[] getStringArray(java.lang.String sArray,
                                                char cDelimiter)
Convenience method to split a String into an array of Strings using a delimiter character. Each array element is trimmed to remove leading and trailing whitespace. An empty String argument returns an array with 0 elements, a non-empty String without the delimiter character in it returns a 1-element array in which that element equals the trimmed String argument. A null String argument returns null.

Parameters:
sArray - the String to be split at each cDelimiter char
cDelimiter - character delimiting the String array elements in sArray
Returns:
the String split into an array, or null if sArray is null.
See Also:
getI18NStringArray

getPreferredSize

public java.awt.Dimension getPreferredSize()
The return value of this method is used to set the size of an JApplicet application. Default behaviour is to use the values of the WIDTH and HEIGHT parameters, or half the screensize for any of these dimensions that is not specified; override as needed.
Overrides:
getPreferredSize in class java.awt.Container
See Also:
JApplicet Framework description

getAppletInfo

public java.lang.String getAppletInfo()
Returns information about this JApplicet; the default implementation returns the JApplicet copyright notice. An JApplicet should override this method to return a String containing information about the author, version, and copyright of the actual JApplicet.
Overrides:
getAppletInfo in class java.applet.Applet
Returns:
a string containing information about the author, version, and copyright of the JApplicet.

getLocale

public java.util.Locale getLocale()
Gets the Locale for the JApplicet, if it has been set, or else the default Locale of the execution environment.

This method overrides Applet.getLocale() to continue gracefully in the case an JApplicet application is not yet put in a parent Container than can supply the Locale. In that case Locale.getDefault() is returned.

Specified by:
getLocale in interface Framework
Overrides:
getLocale in class java.applet.Applet
Returns:
the Locale for the JApplicet.

runAsApplication

public JApplicet runAsApplication(java.lang.String[] args)
                           throws java.lang.IllegalStateException
Brings up a JFrame containing the JApplicet application, and the JApplicet is initted and started. When the JFrame is disposed the JApplicet is stopped and destroyed and System.exit(0) is called.

Equivalent to runAsApplication(args, true).

Parameters:
args - see below
Throws:
java.lang.IllegalStateException - see below
See Also:
runAsApplication(String[] args, boolean swSetActive)

runAsApplication

public JApplicet runAsApplication(java.lang.String[] args,
                                  boolean swSetActive)
                           throws java.lang.IllegalStateException
Creates a JFrame containing the JApplicet application. If swSetActive is true, the JFrame is set visible and the JApplicet is initted and started. If false, calling ((JApplicet.Context)getAppletContext().setActive(true) is needed to set JFrame visible and init and start the JApplicet. In both cases when the JFrame is disposed the JApplicet is stopped and destroyed and System.exit(0) is called.

Equivalent to runAsApplication(args, swSetActive, true, null).

Parameters:
args - see below
swSetActive - see below
Throws:
java.lang.IllegalStateException - see below
See Also:
runAsApplication(String[] args, boolean swSetActive, boolean swCreateFrame, String sName)

runAsApplication

public JApplicet runAsApplication(java.lang.String[] args,
                                  boolean swSetActive,
                                  boolean swCreateFrame,
                                  java.lang.String sName)
                           throws java.lang.IllegalStateException
Creates an application AppletStub and AppletContext for the JApplicet application. One of the runAsApplication variants should be invoked once for each JApplicet application instance, as it performs necessary setup for the application execution context of the JApplicet.

Parameters:
args - commandline parameters, each of the form "optionname", "name=value" or "@propertyfile", with propertyfile the qualified name of a properties file that contains a set of parameter values. Multiple command line parameters of each kind are allowed, where later (to the right) entries override earlier (to the left) entries. Parameter names are case-insensitive; internally they are treated as lowercase. Parameter names in name=value pairs and in optionname may be unique abbreviatons of parameters named in the return value of getParameterInfo(). Parameter names in .properties files must have a "param." prefix (i.e. "param.name=value" or "param.optionname").

swSetActive - if true, runAsApplication activates the JApplicet application; if false, you need to call ((JApplicet.Context)getAppletContext()).setActive(true) yourself at the appropriate time to init and start the JApplicet.

swCreateFrame - If true, the JApplicet is put into a JFrame created by createFrame(); on disposal of this JFrame the JApplicet application is deactivated and it's stop() and destroy() methods are invoked, followed by System.exit(0). If false, you have to host the JApplicet application panel in your own Container and take care of calling ((JApplicet.Context)getAppletContext()).setActive(false) yourself to stop() and destroy the JApplicet application when needed, and call System.exit(int) at the appropriate time when eventual other Applicets or application modules have finished their job (you will have to do this even if you add the JApplicet application to the return value of a call to createFrame()).

sName - name to use for this JApplicet instance in calls to getAppletContext().getApplet(String sName); can be null. Serves intra-JApplicet communication in the case your Application hosts multiple Applicets.
Returns:
this JApplicet (easy for chaining method invokations).
Throws:
java.lang.IllegalStateException - if the JApplicet is already in an AppletContext, either as an applet or as an application
See Also:
Context.setActive
, runAsApplication(String[] args, boolean swSetActive)
, runAsApplication(String[] args)
, createFrame, getI18NParameterInfo, JApplicet.Context#getApplet, Parameters in .properties files, Running an JApplicet application, Code examples

isApplication

public boolean isApplication()
You might want to do something extra when running as application.

NOTE: This method returns false until runAsApplication() is called!

Returns:
true if running as an application, false if running as an applet.
See Also:
runAsApplication

createFrame

public javax.swing.JFrame createFrame()
Creates a frame with the class name both as title and as base name for the icon filename: first ".gif" is appended to try and get an icon image, then ".jpg".

JApplicet applets can use this frame to display content that is unhooked from the Web browser's window, or to parent user information dialogs. This method should not be called before runAsApplication has been called for an JApplicet application.

Note: Not all JVM's turn the transparent area of GIF89 images into a transparent icon area; some just make it a black area.

See Also:
getFrame, runAsApplication

getFrame

public java.awt.Frame getFrame()
Convenience method that returns and always reuses the same JFrame, created by createFrame(). This will be the JFrame holding the JApplicet application, if that was created by JApplicet itself, so that you can for example change the title and/or icon of that JFrame.

This method should not be called before runAsApplication has been called for an JApplicet application.

Specified by:
getFrame in interface Framework
See Also:
getParentFrame, createFrame, runAsApplication

getParentFrame

public java.awt.Frame getParentFrame()
Returns the first parent of this JApplicet that is a Frame (using Component.getParent() to get there).

Use this method preferably to get a good parent for Dialog and Window instances.

Returns:
the first parent Frame or null
See Also:
getFrame

getParameter

public java.lang.String getParameter(java.lang.String sName,
                                     java.lang.String sDefaultValue)
Convenience method to retrieve a named parameter, with fallback to a default value. Parameters originate either from the HTML document for an JApplicet applet, or from the command line arguments supplied to runAsApplication() for an JApplicet application, as also described in the JApplicet Framework overview.
Specified by:
getParameter in interface Framework
Parameters:
sName - the parameter name
sDefaultValue - a default value for the parameter.
Returns:
the value of the named parameter, or sDefaultValue if not found.
See Also:
runAsApplication, ParameterParser

getReservedParameterInfo

protected java.lang.String[][] getReservedParameterInfo()
Returns information about the reserved parameters that are understood by an JApplicet application. They bear no relevance to applets, as they are just equivalents of the HTML <APPLET> tag attributes, so for JApplicet applets the return value is an empty array. An JApplicet that overrides the related method getParameterInfo() need not concatenate it's own parameters to the return value of getReservedParameterInfo().

The JApplicet class itself calls this method only for applications, not for applets; subclasses should not need to call it at all: this method is not private just to enable overriding.

You might want to override this method to hide some or all of the reserved parameter names from your users. The return value should be structured like that of getParameterInfo(), i.e. each array element should itself be an array of 3 Strings, in order the parameter name, it's type, and a description. The parameter names can be abbreviated in commandline arguments. The return String array can also be modified by changing it's String array definition in Applicet_locale.properties.

Returns:
an array describing the parameters JApplicet applications look for.
See Also:
runAsApplication, getI18NStringArray, "java.applet.Applet.getParameterInfo()"

getUsage

protected java.lang.String getUsage()
Convenience method to return a 'typical use' message for display in the usage dialog of an JApplicet application. If the return value is null, the default message is displayed. This default is the return value of getParameterInfo(), formatted according to the MessageFormat pattern definitions called "usage01" and "usage02" in Applicet_locale.properties.

The JApplicet class itself calls this method only for applications, not for applets; subclasses should not need to call it at all: this method is not private just to enable overriding.

Returns:
the default implementation returns null
See Also:
JApplicet.Context.showUsage, formatI18NString, getI18NParameterInfo

getResourceContext

public int getResourceContext()
Returns the context for finding Resources.
Returns:
the context for finding Resources. Can be one of the predefind HFile.CONTEXT_xxx constants.
See Also:
setResourceContext, HFile

setResourceContext

public void setResourceContext(int iResourceContext)
                        throws java.lang.IllegalArgumentException
Sets the context for finding Resources. The default value is set by JApplicet according to the environment, and you will probably never have to change it.
Parameters:
iResourceContext - context for constructing the resource url; must be one of the predefind HFile.CONTEXT_xxx constants.
Throws:
java.lang.IllegalArgumentException - if iResourceContext is not one of the predefined HFile.CONTEXT_xxx constants
See Also:
getResourceContext, getResource, getResourceAsStream, getImage, getAudioClip, play, HFile

getResource

public java.net.URL getResource(java.lang.String sName)
Returns the URL for a resource with a given name, according to the resource context for this JApplicet. This method may but need not return null if no resource content would be found at this URL (e.g. the resource context HFile.CONTEXT_CODEBASE does not check for the existence of the resource refferred to by the returned URL).

Note: Netscape currently (v.4.5) can open an InputStreams on a resource in a .jar file, but it does not handle these resources as URL's. For this reason in a Netscape you cannot get the URL (with getResource()) of such a resource; other JApplicet resource handling methods work fine even in Netscape and for jarred resources.

Parameters:
sName - the (qualified) name of the desired resource
Returns:
a java.net.URL to the resource or null.
See Also:
getResource(String sName, int iResourceContext), getResourceContext, setResourceContext

getResource

public java.net.URL getResource(java.lang.String sName,
                                int iResourceContext)
                         throws java.lang.IllegalArgumentException
Returns the URL for a resource with a given name, according to the specified resource context. This method may but need not return null if no resource content would be found at this URL (e.g. the resource context HFile.CONTEXT_CODEBASE does not check for the existence of the resource refferred to by the returned URL).

In most cases the plain getResource(String) signature will do the job.

Parameters:
sName - the (qualified) name of the desired resource
iResourceContext - context for constructing the resource url; must be one of the predefined HFile.CONTEXT_xxx constants; HFile.CONTEXT_CLASS and HFile.CONTEXT_CLASSSTREAM are treated as equivalent in invocations of this method, as are HFile.CONTEXT_SYSTEM and HFile.CONTEXT_SYSTEMSTREAM, because you cannot get at the URL an InputStream originates from.
Returns:
a java.net.URL to the resource or null.
Throws:
java.lang.IllegalArgumentException - if iResourceContext is not one of the predefined HFile.CONTEXT_xxx constants
See Also:
getResource(String sName), HFile

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String sName)
Returns an InputStream on a resource with a given name, according to the resource context for this JApplicet, or null if no such resource is found.
Specified by:
getResourceAsStream in interface Framework
Parameters:
sName - the (qualified) name of the desired resource
Returns:
a java.io.InputStream on the resource or null; it is good programming practice to close this InputStream when done with it.
See Also:
getResourceAsStream(String sName, int iResourceContext), getResourceContext, setResourceContext

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String sName,
                                               int iResourceContext)
                                        throws java.lang.IllegalArgumentException
Returns an InputStream on a resource with a given name, according to the specified resource context, or null if no such resource is found. In most cases the plain getResourceAsStream(String) signature will do the job.
Specified by:
getResourceAsStream in interface Framework
Parameters:
sName - the (qualified) name of the desired resource
iResourceContext - context for constructing the resource url; must be one of the predefined HFile.CONTEXT_xxx constants.
Returns:
a java.io.InputStream on the resource or null; it is good programming practice to close this InputStream when done with it.
Throws:
java.lang.IllegalArgumentException - if iResourceContext is not one of the predefined HFile.CONTEXT_xxx constants
See Also:
getResourceAsStream(String sName), HFile

getImage

public java.awt.Image getImage(java.lang.String sName)
Utitlity method that does a best effort to get the named Image resource, depending on this JApplicet's resource context and execution environment.
Parameters:
sName - the (qualified) name of the Image resource
Returns:
the Image if found and indeed an Image, else null.
See Also:
getImage(String sName, int iResourceContext), getResourceContext, setResourceConte

getImage

public java.awt.Image getImage(java.lang.String sName,
                               int iResourceContext)
                        throws java.lang.IllegalArgumentException
Gets the named Image resource, either by reading it from the resource's URL or from an InputStream opened on the resource, depending on the iResourceContext parameter. In most cases the plain getImage(String) signature will do the job.
Parameters:
sName - the (qualified) name of the Image resource
iResourceContext - context for opening an URL or InputStream on the resource; must be one of the predefined HFile.CONTEXT_xxx constants.
Returns:
the Image if found and indeed an Image, else null.
Throws:
java.lang.IllegalArgumentException - if iResourceContext is not one of the predefined HFile.CONTEXT_xxx constants
See Also:
getImage(String sName), HFile

readResource

public byte[] readResource(java.io.InputStream is)
                    throws java.io.IOException
Reads an InputStream (typically obtained as the return value of invoking getResourceAsStream) to end into a byte[]. The InputStream is not closed.

getAudioClip

public java.applet.AudioClip getAudioClip(java.lang.String sName)
Utitlity method that does a best effort to get the named AudioClip resource, depending on this JApplicet's resource context and execution environment.
Parameters:
sName - the (qualified) name of the AudioClip resource
Returns:
the AudioClip if found and indeed an AudioClip, else null.
See Also:
getAudioClip(String sName, int iResourceContext), getResourceContext, setResourceContext

getAudioClip

public java.applet.AudioClip getAudioClip(java.lang.String sName,
                                          int iResourceContext)
                                   throws java.lang.IllegalArgumentException
Gets the named AudioClip resource, either by reading it from the resource's URL or from an InputStream opened on the resource, depending on the iResourceContext parameter. In most cases the plain getAudioClip(String) signature will do the job.
Parameters:
sImageName - the (qualified) name of the AudioClip resource
iResourceContext - context for opening an URL or InputStream on the resource; must be one of the predefined HFile.CONTEXT_xxx constants.
Returns:
the AudioClip if found and indeed an AudioClip, else null.
Throws:
java.lang.IllegalArgumentException - if iResourceContext is not one of the predefined HFile.CONTEXT_xxx constants
See Also:
getAudioClip(String sName), HFile

play

public void play(java.lang.String sName)
Utitlity method that does a best effort to play the named AudioClip resource, depending on this JApplicet's resource context and execution environment. Nothing happens if the AudioClip cannot be found.
Parameters:
sName - the (qualified) name of the AudioClip resource
See Also:
play(String sName, int iResourceContext), getResourceContext, setResourceContext

play

public void play(java.lang.String sName,
                 int iResourceContext)
          throws java.lang.IllegalArgumentException
Plays the named AudioClip resource, either by reading it from the resource's URL or from an InputStream opened on the resource, depending on the iResourceContext parameter. Nothing happens if the audio clip cannot be found. In most cases the plain play(String) signature will do the job.
Parameters:
sImageName - the (qualified) name of the AudioClip resource
iResourceContext - context for opening an URL or InputStream on the resource; must be one of the predefined HFile.CONTEXT_xxx constants.
Throws:
java.lang.IllegalArgumentException - if iResourceContext is not one of the predefined HFile.CONTEXT_xxx constants
See Also:
play(String sName), HFile

getI18NString

public java.lang.String getI18NString(java.lang.String sName)
Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet.

This is a convenience method that delegates to the corresponding method in I18NDelegate. If the I18N set is not yet loaded, it is done now.

Parameters:
sName - the property name.
Returns:
the localized String with the specified property name in this I18N properties set, or if not found the name itself as default.
See Also:
getI18NString(String sName, String sDefault), getI18NDelegate, I18NDelegate, "Internationalization support"

getI18NString

public java.lang.String getI18NString(java.lang.String sName,
                                      java.lang.String sDefault)
Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet.

This is a convenience method that delegates to the corresponding method in I18NDelegate. If the I18N set is not yet loaded, it is done now.

Parameters:
sName - the property name.
sDefault - the default value for the localized String.
Returns:
the localized String with the specified property name in this I18N properties set, or if not found the default value.
See Also:
getI18NString(String sName), getI18NDelegate, I18NDelegate, "Internationalization support"

getI18NStringArray

public java.lang.String[] getI18NStringArray(java.lang.String sName,
                                             char cDelimiter)
Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet, and splits it into an array of Strings using the delimiter character. Each array element is trimmed to remove leading and trailing whitespace. An empty String returns an array with 0 elements, a non-empty String without the delimiter character in it returns a 1-element array in which that element equals the trimmed String. A null String returns null.

This is a convenience method that delegates to the corresponding method in I18NDelegate. If the I18N set is not yet loaded, it is done now.

Parameters:
sName - the property name.
cDelimiter - character delimiting the String array elements in the localized String entry in the .properties files.
Returns:
the localized String split into an array, or if not found an array with the name itself as only element.
See Also:
getI18NStringArray(String sName, String sDefault, char cDelimiter), getStringArray, getI18NDelegate, I18NDelegate, "Internationalization support"

getI18NStringArray

public java.lang.String[] getI18NStringArray(java.lang.String sName,
                                             java.lang.String sDefault,
                                             char cDelimiter)
Searches for the localized String with the specified name in the default I18N set of .properties files for this JApplicet, and splits it into an array of Strings using the delimiter character. Each array element is trimmed to remove leading and trailing whitespace. An empty String returns an array with 0 elements, a non-empty String without the delimiter character in it returns a 1-element array in which that element equals the trimmed String. A null String returns null.

This is a convenience method that delegates to the corresponding method in I18NDelegate. If the I18N set is not yet loaded, it is done now.

Parameters:
sName - the property name.
sDefault - the default value for the localized String.
cDelimiter - character delimiting the String array elements in the localized String entry in the .properties files.
Returns:
the localized String split into an array, or if not found the default value split into an array using the same delimiter.
See Also:
getI18NStringArray(String sName, char cDelimiter), getStringArray, getI18NDelegate, I18NDelegate, "Internationalization support"

formatI18NString

public java.lang.String formatI18NString(java.lang.String sPatternName,
                                         java.lang.Object[] aoArgs)
Formats an array of Object arguments to a localized message according to the named pattern; the pattern name is used to look up both the localized pattern as well as localized argument Strings for those Object arguments that are null.

This is a convenience method that delegates to the corresponding method in I18NDelegate. Localized Strings are retrieved from the default I18N set of .properties files. If the I18N set is not yet loaded, it is done now.

Formatting is done through java.text.MessageFormat, using the current locale of the JApplicet (getLocale()). If an Object argument is not null, it is used as such (these Object arguments can be Strings too). If an Object argument is null, it is replaced with the localized String named "patternname.i", where i is the number (0-9) of the argument; if such localized String cannot be found, its name is used as default value.

If no formatting can be done (named pattern not found), a return value is composed of the pattern name and the String representation of the Object arguments that are not null.

Parameters:
sPatternName - the property name of the pattern.
aoArgs - array of Objects to format into the localized pattern String; a null Object aoArgs[i] is replaced by a localized String from the I18N set that has the property name (sPatternName + "." + i)
Returns:
the formatted localized message.
See Also:
formatI18NString(String sPatternName, String sDefaultPattern, Object[] aoArgs), getI18NDelegate, I18NDelegate, "Internationalization support"

formatI18NString

public java.lang.String formatI18NString(java.lang.String sPatternName,
                                         java.lang.String sDefaultPattern,
                                         java.lang.Object[] aoArgs)
Formats an array of Object arguments to a localized message according to the named pattern; the pattern name is used to look up both the localized pattern as well as localized argument Strings for those Object arguments that are null.

This is a convenience method that delegates to the corresponding method in I18NDelegate. Localized Strings are retrieved from the default I18N set of .properties files. If the I18N set is not yet loaded, it is done now.

Formatting is done through java.text.MessageFormat, using the current locale of the JApplicet (getLocale()). If an Object argument is not null, it is used as such (these Object arguments can be Strings too). If an Object argument is null, it is replaced with the localized String named "patternname.i", where i is the number (0-9) of the argument; if such localized String cannot be found, its name is used as default value.

If no formatting can be done (named pattern not found and no default pattern given), a return value is composed of the pattern name and the String representation of the Object arguments that are not null.

Parameters:
sPatternName - the property name of the pattern.
sDefaultPattern - the default pattern to use if the named pattern is not found.
aoArgs - array of Objects to format into the localized pattern String; a null Object aoArgs[i] is replaced by a localized String from the I18N set that has the property name (sPatternName + "." + i)
Returns:
the formatted localized message.
See Also:
formatI18NString(String sPatternName, Object[] aoArgs), getI18NDelegate, I18NDelegate, "Internationalization support"

getI18NParameterInfo

public java.lang.String[][] getI18NParameterInfo(java.lang.String[][] aasDefaultParameterInfo,
                                                 char cDelimiter)
Retrieves localized parameterinfo based on a default array of parameterinfo Strings. Localized Strings for type and description are retrieved from the default I18N set of .properties files, using as key the parameter name prefixed with "info."; type and description entries in the .properties file should be separated by the delimiter character. The parameter names themselves are not localized.

This is a convenience method that delegates to the corresponding method in I18NDelegate. If the I18N set is not yet loaded, it is done now.

An example of an appropriate parameter info definition can be found in be/arci/applet/Applicet.properties.

Parameters:
aasParameterInfo - array of parameter info Strings that acts as default. Each element of the array should be a String array with as first element the parameter name. Subsequent elements can supply default Strings for the type and description of the parameter. Default type and description String elements that are not present in the array or are null, will be replaced by an empty String if no localized String is found for them.

cDelimiter - separator between type and description Strings in the .properties files; one separated the respective Strings are trimmed.
Returns:
a validly structured return value for getParameterInfo().
See Also:
getI18NDelegate, I18NDelegate, "Internationalization support"

getI18NDelegate

public I18NDelegate getI18NDelegate()
Retrieves the I18NDelegate of this JApplicet, giving more control over I18N aspects.
Specified by:
getI18NDelegate in interface Framework
See Also:
I18NDelegate, "Internationalization support"

Applicet Framework for Applets and Applications v2.03