com.droplets.client
Class ComponentAdapter

java.lang.Object
  |
  +--com.droplets.client.ComponentAdapter

public abstract class ComponentAdapter

extends java.lang.Object

Adapter class to encapsulate an AWT Component so the Droplets Client can use it as a custom component.

A custom component for the Droplets Platform is implemented in three classes:

• An AWT Component that will be loaded and run by the Droplets Client
• An adapter, to handle communication between the AWT Component and the Droplets Client
• A server-side proxy, derived from CustomComponent

The first two classes are loaded by the Droplets Client, and need to be installed in a zip file in the DropletsComponent folder.

The third class, the server-side proxy, is deployed on the server.

The ComponentAdapter class is loaded by the Droplets Client, and is responsible for handling the communications between the AWT Component, and the Droplets Client. None of the com.droplets.api classes are available to the ComponentAdapter.

If the ComponentAdapter is not installed on the client machine, a default ComponentAdapter will be created, displaying a cyan box with a black X through it. An error dialog will also be displayed.

Because the ComponentAdapter and its associated classes are run on the client machine, the developer must handle all of the unpleasant porting issues that the Droplets Platform normally shelters developers from.

When developing for Microsoft Windows, the ComponentAdapter and associated classes should be built with JDK 1.1.8, with the dropletcc.zip library added to the classpath. The resulting class files should be placed into a zip file (not a jar).

The resulting zip file should be installed in the Components directory, which is itself in the same directory as the DropletClient.

Constructor Summary

protected

ComponentAdapter() Constructs the ComponentAdapter.

Method Summary

abstract boolean	canStart(java.lang.String hostname, java.lang.String application, boolean isSecure) Checks to see if the AWT Component should be created.
abstract java.awt.Component	getAwtComponent() Get the AWT Component that this CustomComponent is implementing.
java.awt.Image	getImage(java.lang.String imageName) Gets an Image, either from the Droplet Application's image jar, image directory, or an arbitrary URL.
java.lang.String	getParameter(java.lang.String parameterName, java.lang.String defaultValue) Gets a parameter from the params.txt file in the Droplet Application's image directory.
java.lang.String	getVar(java.lang.String varName, java.lang.String defaultValue) Gets a value from the vars tag in Droplet DRP file, or the Applet tags.
void	onCustomAction(java.lang.String actionName, java.lang.String actionArgs) Template method called by the Droplets Client when a custom action has been recieved.
void	onCustomAttributeChanged(java.lang.String attributeName, java.lang.String attributeValue) Template method called by the Droplets Client when a custom attribute has been changed.
void	sendCustomAction(java.lang.String actionName, java.lang.String actionArgs) Sends a custom action, notifying the server's CustomComponent object.
void	setCustomAttribute(java.lang.String attributeName, java.lang.String attributeValue) Sets a custom attribute, and notifies the server's CustomComponent object.
void	setServices(ComponentServices services) Sets the ComponentServices for this ComponentAdapter.
void	start() Initializes the ComponentAdapter, and creates the AWT Component that the adapter is providing.
boolean	waitForImage(java.awt.Image image, boolean widthAndHeightOnly) Waits until an Image previously returned by getImage has actually loaded.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentAdapter

protected ComponentAdapter()

Constructs the ComponentAdapter. Sub-classes should not create their AWT Components in their constructors -- this should happen during the start() method.

All subclasses are required to have a default public constructor.

Method Detail

setServices

public final void setServices(ComponentServices services)

Sets the ComponentServices for this ComponentAdapter. This method is called by the Droplets Client before the canStart(java.lang.String, java.lang.String, boolean) method.

Parameters:

services - The ComponentServices for this ComponentAdapter

canStart

public abstract boolean canStart(java.lang.String hostname,
                                 java.lang.String application,
                                 boolean isSecure)

Checks to see if the AWT Component should be created.

Because custom components can contain any code, care should be taken to avoid exposing potentially dangerous behaviors to unknown servers.

Parameters:

hostname - The hostname of the Droplets Server.

application - The name of the Droplet Application.

isSecure - true if the connection is secure (SSL, HTTPS), false otherwise.

Returns:

true if the AWT Component should be created, false otherwise.

start

public void start()

Initializes the ComponentAdapter, and creates the AWT Component that the adapter is providing. After this method is called, getAwtComponent must return non-null.

getAwtComponent

public abstract java.awt.Component getAwtComponent()

Get the AWT Component that this CustomComponent is implementing. The DropletClient will use this Component for any AWT calls that it needs to make.

Returns:

The AWT Component that this adapter is providing.

onCustomAttributeChanged

public void onCustomAttributeChanged(java.lang.String attributeName,
                                     java.lang.String attributeValue)

Template method called by the Droplets Client when a custom attribute has been changed.

This method is called in response to CustomComponent.setStringCustomAttribute(java.lang.String, java.lang.String, java.lang.String). Attributes are subject to skinning, so the value sent from the server-side proxy may have been overridden by the params.txt file.

Parameters:

attributeName - The name of the custom attribute

attributeValue - The new value of the custom attribute

See Also:

CustomComponent.setStringCustomAttribute(java.lang.String, java.lang.String, java.lang.String)

onCustomAction

public void onCustomAction(java.lang.String actionName,
                           java.lang.String actionArgs)

Template method called by the Droplets Client when a custom action has been recieved.

Parameters:

actionName - The name of the action

actionArgs - Any additional arguments for the action.

getImage

public java.awt.Image getImage(java.lang.String imageName)

Gets an Image, either from the Droplet Application's image jar, image directory, or an arbitrary URL.

If the imageName unqualified name, such as myimage, this method will load myimage.gif from the image jar, or the image directory if there is no image jar.

If the imageName is a URL, the image will be loaded from that URL. The Droplets Redirector will be used, so it is safe to call this method from within an applet.

Parameters:

imageName - The name or URL of the image

Returns:

The image, or null if the image cannot be loaded

getParameter

public java.lang.String getParameter(java.lang.String parameterName,
                                     java.lang.String defaultValue)

Gets a parameter from the params.txt file in the Droplet Application's image directory.

Parameters:

parameterName - The name of the parameter

defaultValue - The default value

Returns:

The value of the parameter, or the default value

getVar

public java.lang.String getVar(java.lang.String varName,
                               java.lang.String defaultValue)

Gets a value from the vars tag in Droplet DRP file, or the Applet tags.

Parameters:

varName - The name of the var

defaultValue - The default value

Returns:

The value of the var, or the default value

waitForImage

public boolean waitForImage(java.awt.Image image,
                            boolean widthAndHeightOnly)

Waits until an Image previously returned by getImage has actually loaded. Call this method when you are ready to draw the image, or need to get its width or height. This method is provided as a convenience for components that do not want to use Java's standard asynchronous image-loading behavior.

Parameters:

image - The image

widthAndHeightOnly - True if you only need the width and height at this point; false if you need the entire image to be ready

Returns:

True if successful; false if the image failed to load

setCustomAttribute

public final void setCustomAttribute(java.lang.String attributeName,
                                     java.lang.String attributeValue)

Sets a custom attribute, and notifies the server's CustomComponent object.

Parameters:

attributeName - The name of the attribute

sttributeValue - The new value for the attribute

sendCustomAction

public final void sendCustomAction(java.lang.String actionName,
                                   java.lang.String actionArgs)

Sends a custom action, notifying the server's CustomComponent object.

Parameters:

actionName - The name of the action

actionArgs - Any additional arguments for the action