be.arci.applet
Class Applicet

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--java.applet.Applet
                          |
                          +--be.arci.applet.Applicet

All Implemented Interfaces:

javax.accessibility.Accessible, Framework, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class Applicet

extends java.applet.Applet

implements Framework

Extends Applet 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 Applicet instead of Applet 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

Applicet.Context The execution environment for Applicet applications (implementing the java.applet.AppletContext interface); also adds functionality, specific for Applicet applications, that need not be distributed with Applicet applets.

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 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

Applicet() It makes no sense to use an Applicet without subclassing; therefor the constructor is protected (unlike Applet's constructor).

Method Summary

java.awt.Frame	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 Applicet; the default implementation returns the Applicet 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 Applicet'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 Frame, created by createFrame().
I18NDelegate	getI18NDelegate() Retrieves the I18NDelegate of this Applicet, 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 Applicet.
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 Applicet.
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 Applicet, 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 Applicet, 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 Applicet'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 Applicet, 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 Applicet 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 Applicet application.
protected java.lang.String[][]	getReservedParameterInfo() Returns information about the reserved parameters that are understood by an Applicet 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 Applicet.
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 Applicet, 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 Applicet application.
boolean	isApplication() You might want to do something extra when running as application.
static boolean	isNetscapeVM() Returns true if the Applicet 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 Applicet'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[].
Applicet	runAsApplication(java.lang.String[] args) Brings up a Frame containing the Applicet application, and the Applicet is initted and started.
Applicet	runAsApplication(java.lang.String[] args, boolean swSetActive) Creates a Frame containing the Applicet application.
Applicet	runAsApplication(java.lang.String[] args, boolean swSetActive, boolean swCreateFrame, java.lang.String sName) Creates an application AppletStub and AppletContext for the Applicet application.
void	setResourceContext(int iResourceContext) Sets the context for finding Resources.

Methods inherited from class java.applet.Applet

destroy, getAccessibleContext, 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, addImpl, 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, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setFont, setLayout, update, 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, processKeyEvent, 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

Applicet

protected Applicet()

It makes no sense to use an Applicet without subclassing; therefor the constructor is protected (unlike Applet's constructor).

Method Detail

isNetscapeVM

public static boolean isNetscapeVM()

Returns true if the Applicet 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 Applicet's plain handling-resources-by-name methods without worrying about Netscape or anything else.

Returns:

true if this Applicet 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 Applicet 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:

Applicet Framework description

getAppletInfo

public java.lang.String getAppletInfo()

Returns information about this Applicet; the default implementation returns the Applicet copyright notice. An Applicet should override this method to return a String containing information about the author, version, and copyright of the actual Applicet.

Overrides:

getAppletInfo in class java.applet.Applet

Returns:

a string containing information about the author, version, and copyright of the Applicet.

getLocale

public java.util.Locale getLocale()

Gets the Locale for the Applicet, 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 Applicet 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 Applicet.

runAsApplication

public Applicet runAsApplication(java.lang.String[] args)
                          throws java.lang.IllegalStateException

Brings up a Frame containing the Applicet application, and the Applicet is initted and started. When the Frame is disposed the Applicet 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 Applicet runAsApplication(java.lang.String[] args,
                                 boolean swSetActive)
                          throws java.lang.IllegalStateException

Creates a Frame containing the Applicet application. If swSetActive is true, the Frame is set visible and the Applicet is initted and started. If false, calling ((Applicet.Context)getAppletContext().setActive(true) is needed to set Frame visible and init and start the Applicet. In both cases when the Frame is disposed the Applicet 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 Applicet 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 Applicet application. One of the runAsApplication variants should be invoked once for each Applicet application instance, as it performs necessary setup for the application execution context of the Applicet.

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 Applicet application; if false, you need to call ((Applicet.Context)getAppletContext()).setActive(true) yourself at the appropriate time to init and start the Applicet.

swCreateFrame - If true, the Applicet is put into a Frame created by createFrame(); on disposal of this Frame the Applicet application is deactivated and it's stop() and destroy() methods are invoked, followed by System.exit(0). If false, you have to host the Applicet application panel in your own Container and take care of calling ((Applicet.Context)getAppletContext()).setActive(false) yourself to stop() and destroy the Applicet 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 Applicet application to the return value of a call to createFrame()).

sName - name to use for this Applicet instance in calls to getAppletContext().getApplet(String sName); can be null. Serves intra-Applicet communication in the case your Application hosts multiple Applicets.

Returns:

this Applicet (easy for chaining method invokations).

Throws:

java.lang.IllegalStateException - if the Applicet 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, Applicet.Context#getApplet, Parameters in .properties files, Running an Applicet 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 java.awt.Frame 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".

Applicet 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 Applicet 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 Frame, created by createFrame(). This will be the Frame holding the Applicet application, if that was created by Applicet itself, so that you can for example change the title and/or icon of that Frame.

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

Specified by:

getFrame in interface Framework

See Also:

getParentFrame, createFrame, runAsApplication

getParentFrame

public java.awt.Frame getParentFrame()

Returns the first parent of this Applicet 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 Applicet applet, or from the command line arguments supplied to runAsApplication() for an Applicet application, as also described in the Applicet 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 Applicet application. They bear no relevance to applets, as they are just equivalents of the HTML <APPLET> tag attributes, so for Applicet applets the return value is an empty array. An Applicet that overrides the related method getParameterInfo() need not concatenate it's own parameters to the return value of getReservedParameterInfo().

The Applicet 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 Applicet 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 Applicet 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 Applicet 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:

Applicet.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 Applicet 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 Applicet. 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 Applicet 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 Applicet, 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 Applicet'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 Applicet'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 Applicet'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 Applicet.

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 Applicet.

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 Applicet, 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 Applicet, 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 Applicet (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 Applicet (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 Applicet, giving more control over I18N aspects.

Specified by:

getI18NDelegate in interface Framework

See Also:

I18NDelegate, "Internationalization support"