org.directwebremoting
Class Browser

java.lang.Object
  org.directwebremoting.Browser

public class Browser
extends java.lang.Object

A collection of APIs that manage reverse ajax APIs.

See withAllSessions(java.lang.Runnable) for a menu of the various different with* methods.

The Runnables that are passed to the with* methods may be executed any number of times between 0 (nothing passes the filter) 1 (where getTargetSessions() returns all the matching ScriptSessions) and X (where X is the number of matching ScriptSessions, with getTargetSessions() returning one of the ScriptSessions on each invocation).

Author:

Joe Walker [joe at getahead dot ltd dot uk]

Constructor Summary

Browser()

Method Summary

static void	close(java.lang.Object proxy) If a browser passes an object or function to DWR then DWR may need to release the reference that DWR keeps.
static java.util.Collection<ScriptSession>	getTargetSessions() This method discovers the sessions that are currently being targeted by browser updates.
static void	withAllSessions(java.lang.Runnable task) Execute some task (represented by a Runnable) and aim the output at all browser window open at all pages in this web application.
static void	withAllSessions(ServerContext serverContext, java.lang.Runnable task) As withAllSessions(Runnable), but for use when there is more than one copy of DWR in the ServletContext.
static void	withAllSessionsFiltered(ScriptSessionFilter filter, java.lang.Runnable task) Execute a task an send the output to a subset of the total list of users.
static void	withAllSessionsFiltered(ServerContext serverContext, ScriptSessionFilter filter, java.lang.Runnable task) As withAllSessionsFiltered(ScriptSessionFilter, Runnable), but for use when there is more than one copy of DWR in the ServletContext.
static void	withCurrentPage(java.lang.Runnable task) Execute a task and aim the output at all the browser windows open at the same page as the current request.
static void	withCurrentPageFiltered(ScriptSessionFilter filter, java.lang.Runnable task) Execute a task and aim the output at a subset of the browser windows open at the same page as the current request.
static void	withPage(ServerContext serverContext, java.lang.String page, java.lang.Runnable task) As withPage(String, Runnable), but for use when there is more than one copy of DWR in the ServletContext.
static void	withPage(java.lang.String page, java.lang.Runnable task) Execute a task and aim the output at all the browser windows open at a given page in this web application.
static void	withPageFiltered(ServerContext serverContext, java.lang.String page, ScriptSessionFilter filter, java.lang.Runnable task) As withPageFiltered(java.lang.String, org.directwebremoting.ScriptSessionFilter, java.lang.Runnable), but for use when there is more than one copy of DWR in a ServletContext.
static void	withPageFiltered(java.lang.String page, ScriptSessionFilter filter, java.lang.Runnable task) Execute a task and aim the output at a subset of the users on a page.
static void	withSession(ServerContext serverContext, java.lang.String sessionId, java.lang.Runnable task) As withSession(String, Runnable), but for use when there is more than one copy of DWR in a ServletContext.
static void	withSession(java.lang.String sessionId, java.lang.Runnable task) Execute a task and aim the output at a specific script session.

Methods inherited from class java.lang.Object

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

Constructor Detail

Browser

public Browser()

Method Detail

withAllSessions

public static void withAllSessions(java.lang.Runnable task)

Execute some task (represented by a Runnable) and aim the output at all browser window open at all pages in this web application. It is likely that a more fine-grained broadcast method will be applicable to most situations. The other with* methods in this class provide extra ways to filter the set of pages to broadcast to. This option could be useful if all pages contain an 'update' area, or to broadcast status information: Window.alert("System reboot in 20mins. Please log off"); To send UI code to browser windows looking at a specific page, see the withPage(java.lang.String, java.lang.Runnable) method. To send to a custom set of browser windows, see the withAllSessionsFiltered(org.directwebremoting.ScriptSessionFilter, java.lang.Runnable) method. To send to a specific session, use withSession(java.lang.String, java.lang.Runnable).

Parameters:

task - A code block to execute

withAllSessions

public static void withAllSessions(ServerContext serverContext,
                                   java.lang.Runnable task)

As withAllSessions(Runnable), but for use when there is more than one copy of DWR in the ServletContext.

For 99% of cases the former method will be much simpler to use.

Parameters:

serverContext - The specific DWR context in which to execute

withAllSessionsFiltered

public static void withAllSessionsFiltered(ScriptSessionFilter filter,
                                           java.lang.Runnable task)

Execute a task an send the output to a subset of the total list of users. The ScriptSessionFilter defines which subset. This method could be used to alert administrators wherever they are on a site about urgent action that need attention.

Parameters:

filter - Used to define the set of browser windows which should receive the update.

task - A code block to execute

withAllSessionsFiltered

public static void withAllSessionsFiltered(ServerContext serverContext,
                                           ScriptSessionFilter filter,
                                           java.lang.Runnable task)

As withAllSessionsFiltered(ScriptSessionFilter, Runnable), but for use when there is more than one copy of DWR in the ServletContext.

For 99% of cases the former method will be much simpler to use.

Parameters:

serverContext - The specific DWR context in which to execute

withCurrentPage

public static void withCurrentPage(java.lang.Runnable task)

Execute a task and aim the output at all the browser windows open at the same page as the current request. No further filtering is performed. This implies that this method is only of use from a DWR created thread. To send to a subset of the browser windows viewing a page, see the withCurrentPageFiltered(org.directwebremoting.ScriptSessionFilter, java.lang.Runnable) method.

Parameters:

task - A code block to execute

withPage

public static void withPage(java.lang.String page,
                            java.lang.Runnable task)

Execute a task and aim the output at all the browser windows open at a given page in this web application. No further filtering is performed. To send to a subset of the browser windows viewing a page, see the withPageFiltered(java.lang.String, org.directwebremoting.ScriptSessionFilter, java.lang.Runnable) method.

Parameters:

page - The page to send to, excluding protocol/host/port specifiers but including context path and servlet path. For example to send to http://example.com:8080/webapp/controller/path/index.html, you should use "/webapp/controller/path/index.html" or since the default PageNormalizer understands default pages, this is the same as sending to browsers viewing "/webapp/controller/path/". To discover the contextPath at runtime you can use javax.servlet.ServletContext#getContextPath with servlet 2.5, or before version 2.5 you can also use ServerContext.getContextPath() or HttpServletRequest.getContextPath().

task - A code block to execute

withPage

public static void withPage(ServerContext serverContext,
                            java.lang.String page,
                            java.lang.Runnable task)

As withPage(String, Runnable), but for use when there is more than one copy of DWR in the ServletContext.

For 99% of cases the former method will be much simpler to use.

Parameters:

serverContext - The specific DWR context in which to execute

withCurrentPageFiltered

public static void withCurrentPageFiltered(ScriptSessionFilter filter,
                                           java.lang.Runnable task)

Execute a task and aim the output at a subset of the browser windows open at the same page as the current request. The filter allows you to select the set of users that will be interested in the update. This implies that this method is only of use from a DWR created thread.

Parameters:

filter - Used to define the set of browser windows which should receive the update.

task - A code block to execute

withPageFiltered

public static void withPageFiltered(java.lang.String page,
                                    ScriptSessionFilter filter,
                                    java.lang.Runnable task)

Execute a task and aim the output at a subset of the users on a page. This method is useful when you have a small number of pages that each have a significant number of functions on them. The filter allows you to select the set of users that will be interested in the update.

Parameters:

page - The page to send to. See withPage(java.lang.String, java.lang.Runnable) for details

filter - Used to define the set of browser windows which should receive the update.

task - A code block to execute

withPageFiltered

public static void withPageFiltered(ServerContext serverContext,
                                    java.lang.String page,
                                    ScriptSessionFilter filter,
                                    java.lang.Runnable task)

As withPageFiltered(java.lang.String, org.directwebremoting.ScriptSessionFilter, java.lang.Runnable), but for use when there is more than one copy of DWR in a ServletContext.

For 99% of cases the former method will be much simpler to use.

Parameters:

serverContext - The specific DWR context in which to execute

withSession

public static void withSession(java.lang.String sessionId,
                               java.lang.Runnable task)

Execute a task and aim the output at a specific script session. This method is likely to be useful for directed updates that originate away from a thread started by the browser window in question. Examples include an instant message, or the results of a slow method invocation. This method is implicit in anything called from a DWR thread, so should not need to be used to send UI updates back to an originating browser.

Parameters:

sessionId - The ScriptSession.id of the browser window

task - A code block to execute

withSession

public static void withSession(ServerContext serverContext,
                               java.lang.String sessionId,
                               java.lang.Runnable task)

As withSession(String, Runnable), but for use when there is more than one copy of DWR in a ServletContext.

For 99% of cases the former method will be much simpler to use.

Parameters:

serverContext - The specific DWR context in which to execute

close

public static void close(java.lang.Object proxy)

If a browser passes an object or function to DWR then DWR may need to release the reference that DWR keeps. If the server-side manifestation of this object is a proxy implemented interface, then there is no place for a close method, so this function allows you to close proxy implemented interfaces.

Parameters:

proxy - An proxy created interface implementation from a browser that we no longer need.

getTargetSessions

public static java.util.Collection<ScriptSession> getTargetSessions()

This method discovers the sessions that are currently being targeted by browser updates.

It will generally only be useful to authors of reverse ajax UI proxy APIs. Using it directly may cause scaling problems

Returns:

The list of current browser windows.