com.droplets.api
Class Application

java.lang.Object
  |
  +--com.droplets.api.InvalidationEventSource
        |
        +--com.droplets.api.Application

public class Application

extends InvalidationEventSource

Represents an individual client's session with a particular Droplet application. Instances should be created by your ApplicationFactory in response to requests by the server. When you create a new window, you will need to add it to this object using addWindow(Window). This class also provides some general-purpose utility methods to accomplish tasks specific to a client session.

Note that there is a restriction on the usage of Application objects. After the Droplet Client corresponding to an Application is no longer connected to the Server, the object's resources may be deallocated, either immediately when the Client disconnects or after a specified period of time. At that point, the object becomes "invalid." All subsequent public method calls will throw an IllegalStateException. Any other objects that hold a reference to this one should register using InvalidationEventSource.addInvalidationListener(com.droplets.api.event.ObjectInvalidationListener) to be notified when the object becomes invalid so that they can release their references. This notification will always come after stop() is called on all of the Application's active windows.

Note that in the ObjectInvalidationListener's event handling code, you must not rely on the fact that the Application's window objects are still valid.

Field Summary

static java.lang.String	MENU_ABOUT Causes the About Droplets dialog box to be displayed.
static java.lang.String	MENU_ADD_TO_WEBPAGE Brings up a dialog with the HTML necessary for embedding this Droplet in a web page.
static java.lang.String	MENU_EMAIL_A_FRIEND Causes the "Send this Droplet to a friend..." dialog box to be displayed.
static java.lang.String	MENU_GO_TO_WEBTOP Sends the user to the www.mydroplets.com website.
static java.lang.String	MENU_HELP Sends the user to the general Droplets help page.
static java.lang.String	MENU_HELP_WITH_DROPLET Sends the user to the help page for this particular Droplet application.
static java.lang.String	MENU_LOG_OFF_AND_EXIT Logs off the user and exits the application.
static java.lang.String	MENU_SAVE_TO_WEBTOP Sends the user to the Droplet Webtop site in order to save the current Droplet.

Constructor Summary

Application(int appToken)
Creates an Application object to handle a user's session with this application.

Method Summary

void	addPollListener(PollListener pl) Adds a listener to be notified when the client polls this application.
void	addWindow(Window window) Adds a window to the application.
void	closeWorkingDialog() Closes the "working" dialog.
void	executeDropletMenuItem(java.lang.String menuItem) Programmatically selects one of the options on the Droplet menu.
java.lang.String	getAuthenticatedUserName() Gets the username by which this user has authenticated
Dripline	getDripline() Gets the Dripline object.
static java.lang.String[]	getDropletMenuItemStrings() Gets an array of all of the valid Droplet menu item string constants that may be passed to executeDropletMenuItem.
int	getPollTime() Returns the poll time in centiseconds.
int	getProtocolVersion() Returns the version number of the protocol currently in use.
java.lang.String	getVariableValue(java.lang.String variableName) Queries the value of one of the variables associated with this application.
WindowFactory	getWindowFactory() Gets the registered window factory.
void	messageBox(java.lang.String title, java.lang.String message) Displays a modal dialog box with an OK button.
void	messageBox(java.lang.String title, java.lang.String message, DialogCloseListener dc) Displays a modal dialog box with an OK button.
void	playSound(java.lang.String sound) Requests that the client play the specified sound.
void	postEvent(java.lang.Runnable event) Posts an event to the Server's internal event queue that will result in the run method being called on the provided object.
void	printPdf(java.lang.String url) Prints the .pdf file pointed to by url.
void	removePollListener(PollListener pl) Removes a poll listener.
void	reportServerError(java.lang.String msg) Tells the Droplet client that a severe server error has occurred.
void	requestAuthentication(java.lang.String message, AuthenticationHandler handler) Pops up a dialog box requesting that the user supply a username and password.
void	requestExit() Tells the Droplet Client to exit, suspending the user's session.
void	saveUrlToFile(java.lang.String url, java.lang.String filename) Asks the client to download a URL and save it into a file that the user chooses.
void	sendFile(Window w, java.lang.String server, int port, java.lang.String fileName) Sends a file to the server that was previously chosen with the file open dialog.
void	setPollTime(int centiseconds) Sets the poll time in centiseconds.
void	setWindowFactory(WindowFactory factory) Registers an object that will be invoked by the Server to recreate the windows in a stored session when the session is deserialized.
void	showDocument(java.lang.String documentUrl, java.lang.String target) Shows a URL in a browser.
void	showErrorDialog(java.lang.String message) Displays a modal error dialog box with an OK button and an error icon.
void	showErrorDialog(java.lang.String message, DialogCloseListener dc) Displays a modal error dialog box with an OK button and an error icon.
void	showOpenDialog(Window w) Puts up a File Open dialog on the client.
void	showWorkingDialog(java.lang.String title, java.lang.String message, boolean autoClose) Displays a "working" dialog with the given title and message.
void	startDroplet(java.lang.String address, int port, java.lang.String imageDir, java.lang.String calc, java.lang.String title, java.lang.String vars) Starts a Droplet on the client with the given Droplet parameters.

Methods inherited from class com.droplets.api.InvalidationEventSource

addInvalidationListener, ensureValid, fireInvalidationEvent, invalidate, isValid, removeInvalidationListener

Methods inherited from class java.lang.Object

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

Field Detail

MENU_ABOUT

public static final java.lang.String MENU_ABOUT

Causes the About Droplets dialog box to be displayed.

MENU_EMAIL_A_FRIEND

public static final java.lang.String MENU_EMAIL_A_FRIEND

Causes the "Send this Droplet to a friend..." dialog box to be displayed.

MENU_GO_TO_WEBTOP

public static final java.lang.String MENU_GO_TO_WEBTOP

Sends the user to the www.mydroplets.com website.

MENU_SAVE_TO_WEBTOP

public static final java.lang.String MENU_SAVE_TO_WEBTOP

Sends the user to the Droplet Webtop site in order to save the current Droplet.

MENU_HELP

public static final java.lang.String MENU_HELP

Sends the user to the general Droplets help page.

MENU_HELP_WITH_DROPLET

public static final java.lang.String MENU_HELP_WITH_DROPLET

Sends the user to the help page for this particular Droplet application. A page for this application must have been set up, otherwise the user will get a "404: File not found" error.

MENU_ADD_TO_WEBPAGE

public static final java.lang.String MENU_ADD_TO_WEBPAGE

Brings up a dialog with the HTML necessary for embedding this Droplet in a web page.

MENU_LOG_OFF_AND_EXIT

public static final java.lang.String MENU_LOG_OFF_AND_EXIT

Logs off the user and exits the application. This is useful to reset the auto-login feature.

Constructor Detail

Application

public Application(int appToken)

Creates an Application object to handle a user's session with this application.

Parameters:

appToken - the token that the server passed into ApplicationFactory.createApplication(int)

Method Detail

setWindowFactory

public void setWindowFactory(WindowFactory factory)

Registers an object that will be invoked by the Server to recreate the windows in a stored session when the session is deserialized. A WindowFactory must be registered in order to support serialization.

Parameters:

factory - the WindowFactory object

getWindowFactory

public WindowFactory getWindowFactory()

Gets the registered window factory.

Returns:

the WindowFactory

addWindow

public void addWindow(Window window)

Adds a window to the application.

Parameters:

window - the window

messageBox

public void messageBox(java.lang.String title,
                       java.lang.String message)

Displays a modal dialog box with an OK button.

Parameters:

title - text to be displayed in the title bar of the dialog box

message - text in the main panel of the dialog box

messageBox

public void messageBox(java.lang.String title,
                       java.lang.String message,
                       DialogCloseListener dc)

Displays a modal dialog box with an OK button. Notifies the listener when it is closed

Parameters:

title - text to be displayed in the title bar of the dialog box

message - text in the main panel of the dialog box

dc - the close listener that will be notified on close. Its handleClose method is called with true if the client supports the call and false if it does not.

showErrorDialog

public void showErrorDialog(java.lang.String message)

Displays a modal error dialog box with an OK button and an error icon.

Parameters:

message - text in the main panel of the dialog box

showErrorDialog

public void showErrorDialog(java.lang.String message,
                            DialogCloseListener dc)

Displays a modal error dialog box with an OK button and an error icon. Notifies the listener when it is closed

Parameters:

message - text in the main panel of the dialog box

dc - the close listener that will be notified on close. Its handleClose method is called with true if the client supports the call and false if it does not.

showWorkingDialog

public void showWorkingDialog(java.lang.String title,
                              java.lang.String message,
                              boolean autoClose)

Displays a "working" dialog with the given title and message. This is a dialog that you can display while your application performs some time consuming task. If autoClose is false, then call closeWorkingDialog() when you want the dialog to close.

Parameters:

title - text to be displayed in the title bar of the dialog box

message - the message that appears on the dialog.

autoClose - true if you want the dialog to automatically close when the event is handled. If autoClose is false, then call closeWorkingDialog() when you want the dialog to close.

See Also:

closeWorkingDialog()

closeWorkingDialog

public void closeWorkingDialog()

Closes the "working" dialog.

See Also:

showWorkingDialog(java.lang.String, java.lang.String, boolean)

requestExit

public void requestExit()

Tells the Droplet Client to exit, suspending the user's session. Does not block until the exit takes place. It is conceivable that the Client will not be able to exit immediately -- if it has a modal dialog box open, for example.

getDropletMenuItemStrings

public static java.lang.String[] getDropletMenuItemStrings()

Gets an array of all of the valid Droplet menu item string constants that may be passed to executeDropletMenuItem.

Returns:

the array of all Droplet menu items

executeDropletMenuItem

public void executeDropletMenuItem(java.lang.String menuItem)

Programmatically selects one of the options on the Droplet menu. The Droplet menu is the one represented by the small green Droplet icon in the lower left corner of the main Droplet application window.

Parameters:

menuItem - must be one of the valid values representing items in the menu, all of which are stored in public static final Strings in this class (see Application above).

getAuthenticatedUserName

public java.lang.String getAuthenticatedUserName()

Gets the username by which this user has authenticated

Returns:

the username by which this user has authenticated, or null if the current user has not been authenticated

reportServerError

public void reportServerError(java.lang.String msg)

Tells the Droplet client that a severe server error has occurred. The client will disconnect, then attempt to reconnect.

Parameters:

msg - text for the Droplet Client to write to its log. It is also displayed to the user while the reconnect takes place.

saveUrlToFile

public void saveUrlToFile(java.lang.String url,
                          java.lang.String filename)

Asks the client to download a URL and save it into a file that the user chooses.

This method operates asynchronously, returning before the client has completed the operation. Therefore, the fact that this method returns does not necessarily mean that the operation succeeded. If the provided URL is invalid, an error dialog will be shown to the user.

Parameters:

url - the URL to download

filename - the filename to suggest to the user, or null to suggest nothing in particular

showOpenDialog

public void showOpenDialog(Window w)

Puts up a File Open dialog on the client. When the user chooses a file, any object registered with the window's addOpenDialogListener will be notified with the filename. They may opt to call sendFile to have the client send the file to the server.

Parameters:

w - The window to associate this open dialog with

See Also:

sendFile(com.droplets.api.Window, java.lang.String, int, java.lang.String), Window.addOpenDialogListener(com.droplets.api.event.OpenDialogListener)

sendFile

public void sendFile(Window w,
                     java.lang.String server,
                     int port,
                     java.lang.String fileName)

Sends a file to the server that was previously chosen with the file open dialog. When the user chooses a file, any object registered with the window's addOpenDialogListener will be notified with the filename. The client will use the PUT method of the web server you specify.

Parameters:

w - The window to associated with this open dialog

server - The internet address of the machine with the web server to PUT the file to

port - The port the web server is listening on

fileName - the server file name.

See Also:

showOpenDialog(com.droplets.api.Window), Window.addOpenDialogListener(com.droplets.api.event.OpenDialogListener)

getVariableValue

public java.lang.String getVariableValue(java.lang.String variableName)

Queries the value of one of the variables associated with this application. The return value is always a String by default, though you can manually convert them to other types if desired.

There are two sets of variables that can be queried with this method:

• Built-in variables with standard names allow you to obtain certain information about the application and the client.
• User-defined variables. These are specified in the vars Droplet parameter and may have any arbitrary name and value.

Variables which can be read include the following:

• AppName - the application name
• GmtOffset - Difference between client-side time and Greenwich Mean Time (in hours); takes the format (+100 or -100)
• Browser - Client-side browser, "standalone" if not an applet
• ImageDir - URL of the application's image directory
• IsSecure - "1" if the connection is secure (SSL, HTTPS), "0" otherwise
• OS - the client-side operating system
• ScreenHeight - Client-side screen height in pixels
• ScreenWidth - Client-side screen width in pixels

In addition, any custom variables defined in the application's DRP file or the application skin's params.txt file will be available as well.

Parameters:

attributeName - the name of the variable to query

Returns:

the value of the variable, or null if the variable is undefined

requestAuthentication

public void requestAuthentication(java.lang.String message,
                                  AuthenticationHandler handler)

Pops up a dialog box requesting that the user supply a username and password.

Authentication is an asynchronous operation. Instead of this function returning a flag for whether the authentication succeeded or not, the caller supplies an AuthenticationHandler that will be called when the operation completes. This method simply returns immediately. See AuthenticationHandler for details on how to interpret the results of the authentication request.

Note that this function allows for deferred authentication: you can allow the user to begin using the application without authenticating, only calling this method when the user requests an operation that requires authentication. If your application requires that the user authenticate herself to run at all, you should implement the ApplicationFactory.getRequiresImmediateAuthentication() method in your ApplicationFactory to return true. If you do that, then the fact that the application has started guarantees that the user is already authenticated.

Parameters:

message - a message to display to the user in the authentication dialog box

handler - an object that will be called when the user completes (or cancels) the authentication. If you have already called this method on this object and supplied an AuthenticationHandler, pass null to leave that handler in place.

Throws:

NullPointerException - if no handler has ever been passed in and the handler argument is null

postEvent

public void postEvent(java.lang.Runnable event)

Posts an event to the Server's internal event queue that will result in the run method being called on the provided object. This allows you to designate arbitrary code to be executed in a Server event-processing thread.

If your application code creates any threads that need to update the state of GUI components or call methods on the Application object, you should make sure that those threads never do so directly. Instead, wrap the calls in Runnable objects and pass them to this method. Otherwise, data corruption is likely to occur.

If the run method throws an unchecked exception, it will be caught and logged by the Server. Execution of other events will continue normally.

Note that the event that you pass in is posted to the end of the queue. Therefore, all other events that have already arrived (for example, actions the user has taken on the front end) are processed before this one. Even if there are no others on the queue, this method returns immediately, before the newly posted event is processed.

Also note that although it is unnecessary, calling this method from a Server thread has no harmful effects and functions in exactly the same way as when it is called from an application thread. The event is still be posted to the end of the queue.

This mechanism for avoiding integrity problems between threads is essentially the same as the one used by AWT and Swing. The Droplet Server event queue is analogous to java.awt.EventQueue, Server threads are analogous to the EventDispatchThread, and the postEvent method is analogous to both java.awt.EventQueue.invokeLater() and javax.swing.SwingUtilities.invokeLater(). Therefore, explanations in any documentation or texts about those packages will generally apply to the Droplet environment as well.

Parameters:

event - the Runnable to be executed by a Server thread

Throws:

NullPointerException - if the argument is null

showDocument

public void showDocument(java.lang.String documentUrl,
                         java.lang.String target)

Shows a URL in a browser. The target is used to refer to the frame of the browser that will be used to show the document. The following targets are reserved

_self: Shows in the frame of the droplet (if droplet is running in a browser)
_parent: Show in the parent frame of the droplet (if droplet is running in a browser)
_top: Show in topmost frame (if droplet is running in a browser)
_blank: Show in a new unnamed top-level window

all other names behave like _blank but are named and can be referred to in subsequent showDocument calls

Parameters:

documentUrl - a url to the document to be showed

target - the target frame in the browser

printPdf

public void printPdf(java.lang.String url)

Prints the .pdf file pointed to by url.

Parameters:

url - the .pdf file to print

startDroplet

public void startDroplet(java.lang.String address,
                         int port,
                         java.lang.String imageDir,
                         java.lang.String calc,
                         java.lang.String title,
                         java.lang.String vars)

Starts a Droplet on the client with the given Droplet parameters. This is not implemented in Applet versions of the client.

Parameters:

address - the network address of the Droplet Server. Use null or "" to indicate that the address is the same as the calling Droplet

port - the network port of the Droplet Server. Use -1 to indicate that the port is the same as the calling Droplet.

imageDir - the base URL of images for the Droplet. Use null to indicate that the imageDir is the same as the calling Droplet.

calc - the calc (Droplet Application Name) of the Droplet. Use null or "" to indicate that the calc is the same as the calling Droplet.

title - the text on the title bar of the Droplet. Use null to indicate that the title is the same as the calling Droplet.

vars - the user variables of the Droplet. Use null to indicate that the vars is the same as the calling Droplet.

getPollTime

public int getPollTime()

Returns the poll time in centiseconds. The poll time is used by HTTP connected clients to poll for changed data. -1 indicates no polling.

Returns:

the poll time

getProtocolVersion

public int getProtocolVersion()

Returns the version number of the protocol currently in use.

setPollTime

public void setPollTime(int centiseconds)

Sets the poll time in centiseconds. The poll time is used by clients to poll for changed data. Set to -1 to indicate no polling.

Parameters:

centiseconds - the desired poll time (or -1 for no polling)

See Also:

addPollListener(com.droplets.api.event.PollListener), removePollListener(com.droplets.api.event.PollListener)

playSound

public void playSound(java.lang.String sound)

Requests that the client play the specified sound. Currently, only Sun Audio format (.au) is supported. A future version of the Droplets Client will be able to play WAVE format sounds.

The sound parameter may be either a URL, or the name of a sound file in the application's imageDir. The file extension must be provided, it will not be assumed.

Example:

myApp.playSound("http://www.sdkhfksjfhskafh.com/capybara.au");
myApp.playSound("capybara.au"); // From imageDir

Parameters:

sound - the sound to play

Since:

Droplets API 2.26

addPollListener

public void addPollListener(PollListener pl)

Adds a listener to be notified when the client polls this application.

Parameters:

pl - the listener to add

See Also:

setPollTime(int), removePollListener(com.droplets.api.event.PollListener)

removePollListener

public void removePollListener(PollListener pl)

Removes a poll listener. Note that all listeners will be automatically removed upon closing - no need for client code to do that.

Parameters:

pl - the listener to remove

See Also:

setPollTime(int), addPollListener(com.droplets.api.event.PollListener)

getDripline

public Dripline getDripline()

Gets the Dripline object. Must be done before using the Dripline class methods elsewhere in your application logic.