Package org.eclipse.rap.rwt.service

## Interface UISession

    public interface UISession

The `UISession` represents the current instance of the UI.

In contrast to the `HttpSession` it is possible to register a listener that is notified before the session is destroyed. This listener can be used to cleanup on session shutdown with the UI session still intact.

Since:
  2.0

### Method Summary

All Methods Instance Methods Abstract Methods
`boolean` `addUISessionListener​(UISessionListener listener)` Adds a `UISessionListener` to this UI session.
`void` `exec​(java.lang.Runnable runnable)` Executes the given runnable in the context of this UI session.
`ApplicationContext` `getApplicationContext()` Returns the ApplicationContext this UISession belongs to.
`java.lang.Object` `getAttribute​(java.lang.String name)` Returns the object bound with the specified name in this UI session, or `null` if no object is bound under the name.
`java.util.Enumeration<java.lang.String>` `getAttributeNames()` Returns an `Enumeration` of the names of all objects bound to this UI session.
`Client` `getClient()` Returns a representation of the client that is connected with the server in this UI session.
`Connection` `getConnection()` Returns the connection used to communicate with the client that is connected to this UI session.
`HttpSession` `getHttpSession()` Returns the underlying HttpSession instance.
`java.lang.String` `getId()` Returns a unique identifier for this UI session.
`java.util.Locale` `getLocale()` Returns the preferred `Locale` for this UI session.
`boolean` `isBound()` Returns whether this UI session is bound to the underlying `HttpSession` or not.
`boolean` `removeAttribute​(java.lang.String name)` Removes the object bound with the specified name from this UI session.
`boolean` `removeUISessionListener​(UISessionListener listener)` Removes a `UISessionListener` from this UI session.
`boolean` `setAttribute​(java.lang.String name, java.lang.Object value)` Binds an object to this UI Session, using the name specified.
`void` `setLocale​(java.util.Locale locale)` Sets the preferred `Locale` for this UI session.

### Method Detail

#### setAttribute

    boolean setAttribute​(java.lang.String name,
                         java.lang.Object value)

Binds an object to this UI Session, using the name specified. If an object of the same name is already bound to the UI session, the object is replaced.

If the value is null, this has the same effect as calling `removeAttribute()`.``

Parameters:
  `name` - the name to which the object is bound; cannot be `null`
  `value` - the object to be bound
Returns:
  `true` if the attribute was set or `false` if the attribute could not be set because the session was invalidated.

#### getAttribute

    java.lang.Object getAttribute​(java.lang.String name)

Returns the object bound with the specified name in this UI session, or `null` if no object is bound under the name.

Parameters:
  `name` - a string specifying the name of the object; cannot be null
Returns:
  the object bound with the specified name or `null` if no object is bound with this name

#### removeAttribute

    boolean removeAttribute​(java.lang.String name)

Removes the object bound with the specified name from this UI session. If no object is bound with the specified name, this method does nothing.

Parameters:
  `name` - The name of the object to remove from this UI session, must not be `null`
Returns:
  `true` if the attribute was removed or `false` if the attribute could not be removed because the session was invalidated
See Also:
  `isBound()`

#### getAttributeNames

    java.util.Enumeration<java.lang.String> getAttributeNames()

Returns an `Enumeration` of the names of all objects bound to this UI session.

Returns:
  An `Enumeration` of strings that contains the names of all objects bound to this UI session or an empty enumeration if the underlying session was invalidated
See Also:
  `isBound()`

#### getId

    java.lang.String getId()

Returns a unique identifier for this UI session.

Returns:
  the unique identifier for this UI session

#### addUISessionListener

    boolean addUISessionListener​(UISessionListener listener)

Adds a `UISessionListener` to this UI session. UISessionListeners are used to receive a notification before the UI session is destroyed. If the given listener was already added the method has no effect.

If the UI session is already destroyed or is about to be destroyed the listener will not be added. In this case, this method returns `false`. A return value of `true` ensures that the listener is registered and will be called.

Parameters:
  `listener` - the listener to be added
Returns:
  `true` if the listener was added and will be called, or `false` if the listener could not be added
See Also:
  `isBound()`

#### removeUISessionListener

    boolean removeUISessionListener​(UISessionListener listener)

Removes a `UISessionListener` from this UI session. UISessionListeners are used to receive notifications before the UI session is destroyed. If the given listener was not added to the session store this method has no effect.

If the UI session is already destroyed or is about to be destroyed the listener will not be removed. In this case, this method returns `false`. A return value of `true` ensures that the listener is removed and will not be called anymore.

Parameters:
  `listener` - the listener to be removed
Returns:
  `true` if the listener was removed and will not be called anymore, or `false` if the listener could not be removed
See Also:
  `isBound()`

#### getApplicationContext

    ApplicationContext getApplicationContext()

Returns the ApplicationContext this UISession belongs to.

Returns:
  the application context for this UI session
Since:
  2.1

#### getHttpSession

    HttpSession getHttpSession()

Returns the underlying HttpSession instance.

Returns:
  the HttpSession instance

#### isBound

    boolean isBound()

Returns whether this UI session is bound to the underlying `HttpSession` or not. If the session store is unbound it behaves as if the HTTP session it belonged to was invalidated.

Returns:
  true if the session store is bound, false otherwise.

#### getClient

    Client getClient()

Returns a representation of the client that is connected with the server in this UI session.

Returns:
  The client for this UI session, never `null`

#### getConnection

    Connection getConnection()

Returns the connection used to communicate with the client that is connected to this UI session.

Returns:
  the connection for this UI session, never `null`

#### getLocale

    java.util.Locale getLocale()

Returns the preferred `Locale` for this UI session. The result reflects the locale that has been set using `setLocale(Locale)`. If no locale has been set on this UISession, the locale will be taken from client using the `ClientInfo` service. If the client request doesn't provide a preferred locale, then this method returns the default locale for the server.

Returns:
  the preferred locale for the client, or the default system locale, never `null`
See Also:
  `setLocale(Locale)`

#### setLocale

    void setLocale​(java.util.Locale locale)

Sets the preferred `Locale` for this UI session. The value set can be retrieved using `getLocale()`.

Parameters:
  `locale` - the locale to set, or `null` to reset
See Also:
  `getLocale()`

#### exec

    void exec​(java.lang.Runnable runnable)

Executes the given runnable in the context of this UI session. The runnable will be executed in the calling thread but with a simulated context so that calls to `RWT.getUISession` will return this UISession even in a background thread.

Note: this method is discouraged. It is only kept for compatibility. New code should access the UISession directly.

Parameters:
  `runnable` - the runnable to execute in the context of this UI session
See Also:
  `SingletonUtil`