org.red5.server.so

## Class SharedObject

- java.lang.Object
- - org.red5.server.AttributeStore
  - - org.red5.server.so.SharedObject

All Implemented Interfaces:
  IAttributeStore, ICastingAttributeStore, IPersistable, ISharedObjectStatistics, IStatisticsBase, AttributeStoreMXBean, Constants

Direct Known Subclasses:
  ClientSharedObject

    public class SharedObject
    extends AttributeStore
    implements ISharedObjectStatistics, IPersistable, Constants

Represents shared object on server-side. Shared Objects in Flash are like cookies that are stored on client side. In Red5 and Flash Media Server there's one more special type of SOs : remote Shared Objects. These are shared by multiple clients and synchronized between them automatically on each data change. This is done asynchronously, used as events handling and is widely used in multiplayer Flash online games. Shared object can be persistent or transient. The difference is that first are saved to the disk and can be accessed later on next connection, transient objects are not saved and get lost each time they last client disconnects from it. Shared Objects has name identifiers and path on server's HD (if persistent). On deeper level server-side Shared Object in this implementation actually uses IPersistenceStore to delegate all (de)serialization work. SOs store data as simple map, that is, "name-value" pairs. Each value in turn can be complex object or map. All access to methods that change properties in the SO must be properly synchronized for multi-threaded access.

### Field Summary

Fields
`protected AtomicInteger` `acquireCount` Number of times the SO has been acquired
`protected AtomicInteger` `changeStats` Counts number of "change" events.
`protected AtomicInteger` `deleteStats` Counts number of "delete" events.
`protected long` `lastModified` Last modified timestamp
`protected CopyOnWriteArraySet<IEventListener>` `listeners` Listeners
`protected StatisticsCounter` `listenerStats` Manages listener statistics.
`protected static org.slf4j.Logger` `log` Logger
`protected boolean` `modified` Has changes? flag
`protected String` `name` Shared Object name (identifier)
`protected SharedObjectMessage` `ownerMessage` Owner event
`protected String` `path` SO path
`protected boolean` `persistent` true if the SharedObject was stored by the persistence framework (NOT in database, just plain serialization to the disk) and can be used later on reconnection
`protected AtomicInteger` `sendStats` Counts number of "send message" events.
`protected IEventListener` `source` Event listener, actually RTMP connection
`protected IPersistenceStore` `storage` Object that is delegated with all storage work for persistent SOs
`protected ConcurrentLinkedQueue<ISharedObjectEvent>` `syncEvents` Synchronization events
`protected AtomicInteger` `updateCounter` Number of pending update operations
`protected AtomicInteger` `version` Version.

### Fields inherited from class org.red5.server.AttributeStore

`attributes`

### Fields inherited from interface org.red5.server.api.persistence.IPersistable

`TRANSIENT_PREFIX`

### Fields inherited from interface org.red5.server.net.rtmp.message.Constants

`HANDSHAKE_SIZE, HEADER_CONTINUE, HEADER_NEW, HEADER_SAME_SOURCE, HEADER_TIMER_CHANGE, MEDIUM_INT_MAX, SO_CLIENT_CLEAR_DATA, SO_CLIENT_DELETE_DATA, SO_CLIENT_INITIAL_DATA, SO_CLIENT_SEND_MESSAGE, SO_CLIENT_STATUS, SO_CLIENT_UPDATE_ATTRIBUTE, SO_CLIENT_UPDATE_DATA, SO_CONNECT, SO_DELETE_ATTRIBUTE, SO_DISCONNECT, SO_SEND_MESSAGE, SO_SET_ATTRIBUTE, SOURCE_TYPE_LIVE, SOURCE_TYPE_VOD, TYPE_ABORT, TYPE_AGGREGATE, TYPE_AUDIO_DATA, TYPE_BYTES_READ, TYPE_CHUNK_SIZE, TYPE_CLIENT_BANDWIDTH, TYPE_EDGE_ORIGIN, TYPE_FLEX_MESSAGE, TYPE_FLEX_SHARED_OBJECT, TYPE_FLEX_STREAM_SEND, TYPE_INVOKE, TYPE_NOTIFY, TYPE_PING, TYPE_SERVER_BANDWIDTH, TYPE_SHARED_OBJECT, TYPE_STREAM_METADATA, TYPE_VIDEO_DATA`

### Constructor Summary

Constructors
Constructor and Description
`SharedObject()` Constructs a new SharedObject.
`SharedObject(Input input)` Constructs new SO from Input object
`SharedObject(Map<String,Object> data, String name, String path, boolean persistent)` Creates new SO from given data map, name, path and persistence option
`SharedObject(Map<String,Object> data, String name, String path, boolean persistent, IPersistenceStore storage)` Creates new SO from given data map, name, path, storage object and persistence option
`SharedObject(String name, String path, boolean persistent)` Creates new SO from given data map, name, path and persistence option
`SharedObject(String name, String path, boolean persistent, IPersistenceStore storage)` Creates new SO from given data map, name, path, storage object and persistence option

### Method Summary

Methods
`void` `acquire()` Prevent shared object from being released.
`protected void` `beginUpdate()` Begin update of this Shared Object.
`protected void` `beginUpdate(IEventListener listener)` Begin update of this Shared Object and setting listener
`protected void` `checkRelease()` Check if shared object must be released.
`protected boolean` `clear()` Deletes all the attributes and sends a clear event to all listeners.
`protected void` `close()` Detaches a reference from this shared object, reset it's state, this will destroy the reference immediately.
`void` `deserialize(Input input)` Load the object from the passed input stream.
`protected void` `endUpdate()` End update of this Shared Object.
`int` `getActiveListeners()` Return current number of subscribed listeners.
`Object` `getAttribute(String name, Object value)` Return attribute by name and set if it doesn't exist yet.
`long` `getCreationTime()` Return the timestamp the object was created.
`Map<String,Object>` `getData()` Getter for data.
`long` `getLastModified()` Returns the timestamp when the object was last modified.
`Set<IEventListener>` `getListeners()` Get event listeners.
`int` `getMaxListeners()` Return maximum number of concurrent subscribed listenes.
`String` `getName()` Return the name of the shared object.
`String` `getPath()` Returns the path of the persistent object.
`IPersistenceStore` `getStore()` Returns the persistence store this object is stored in
`int` `getTotalChanges()` Return number of attribute changes.
`int` `getTotalDeletes()` Return number of attribute deletes.
`int` `getTotalListeners()` Return total number of subscribed listeners.
`int` `getTotalSends()` Return number of times a message was sent.
`String` `getType()` Returns the type of the persistent object.
`int` `getVersion()` Getter for version.
`boolean` `isAcquired()` Check if shared object currently is acquired.
`boolean` `isPersistent()` Check if the shared object is persistent.
`protected void` `notifyModified()` Send notification about modification of SO
`protected void` `register(IEventListener listener)` Register event listener
`void` `release()` Release previously acquired shared object.
`boolean` `removeAttribute(String name)` Removes attribute with given name
`void` `removeAttributes()` Remove all attributes (clear Shared Object)
`protected void` `returnAttributeValue(String name)` Return an attribute value to the owner.
`protected void` `returnError(String message)` Return an error message to the client.
`protected void` `sendMessage(String handler, List<?> arguments)` Broadcast event to event handler
`protected void` `sendUpdates()` Send update notification over data channel of RTMP connection
`void` `serialize(Output output)` Write the object to the passed output stream.
`boolean` `setAttribute(String name, Object value)` Set value of attribute with given name
`void` `setAttributes(IAttributeStore values)` Set attributes as attributes store.
`void` `setAttributes(Map<String,Object> values)` Set attributes as map.
`void` `setName(String name)` Set the name of the persistent object.
`void` `setPath(String path)` Set the path of the persistent object.
`void` `setPersistent(boolean persistent)` Set the persistent flag of the object.
`void` `setStore(IPersistenceStore store)` Store a reference to the persistence store in the object.
`protected void` `unregister(IEventListener listener)` Unregister event listener

### Methods inherited from class org.red5.server.AttributeStore

`filterNull, from, getAttribute, getAttributeNames, getAttributes, getBoolAttribute, getByteAttribute, getDoubleAttribute, getIntAttribute, getListAttribute, getLongAttribute, getMapAttribute, getSetAttribute, getShortAttribute, getStringAttribute, hasAttribute`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### log

    protected static org.slf4j.Logger log

Logger

#### name

    protected String name

Shared Object name (identifier)

#### path

    protected String path

SO path

#### persistent

    protected boolean persistent

true if the SharedObject was stored by the persistence framework (NOT in database, just plain serialization to the disk) and can be used later on reconnection

#### storage

    protected IPersistenceStore storage

Object that is delegated with all storage work for persistent SOs

#### version

    protected AtomicInteger version

Version. Used on synchronization purposes.

#### updateCounter

    protected AtomicInteger updateCounter

Number of pending update operations

#### modified

    protected boolean modified

Has changes? flag

#### lastModified

    protected long lastModified

Last modified timestamp

#### ownerMessage

    protected SharedObjectMessage ownerMessage

Owner event

#### syncEvents

    protected ConcurrentLinkedQueue<ISharedObjectEvent> syncEvents

Synchronization events

#### listeners

    protected CopyOnWriteArraySet<IEventListener> listeners

Listeners

#### source

    protected IEventListener source

Event listener, actually RTMP connection

#### acquireCount

    protected AtomicInteger acquireCount

Number of times the SO has been acquired

#### listenerStats

    protected StatisticsCounter listenerStats

Manages listener statistics.

#### changeStats

    protected AtomicInteger changeStats

Counts number of "change" events.

#### deleteStats

    protected AtomicInteger deleteStats

Counts number of "delete" events.

#### sendStats

    protected AtomicInteger sendStats

Counts number of "send message" events.

### Constructor Detail

#### SharedObject

    public SharedObject()

Constructs a new SharedObject.

#### SharedObject

    public SharedObject(Input input)
                 throws IOException

Constructs new SO from Input object

Parameters:
  `input` - Input source
Throws:
  `IOException` - I/O exception
See Also:
  `Input`

#### SharedObject

    public SharedObject(String name,
                String path,
                boolean persistent)

Creates new SO from given data map, name, path and persistence option

Parameters:
  `name` - SO name
  `path` - SO path
  `persistent` - SO persistence

#### SharedObject

    public SharedObject(String name,
                String path,
                boolean persistent,
                IPersistenceStore storage)

Creates new SO from given data map, name, path, storage object and persistence option

Parameters:
  `name` - SO name
  `path` - SO path
  `persistent` - SO persistence
  `storage` - Persistence storage

#### SharedObject

    public SharedObject(Map<String,Object> data,
                String name,
                String path,
                boolean persistent)

Creates new SO from given data map, name, path and persistence option

Parameters:
  `data` - Data
  `name` - SO name
  `path` - SO path
  `persistent` - SO persistence

#### SharedObject

    public SharedObject(Map<String,Object> data,
                String name,
                String path,
                boolean persistent,
                IPersistenceStore storage)

Creates new SO from given data map, name, path, storage object and persistence option

Parameters:
  `data` - Data
  `name` - SO name
  `path` - SO path
  `persistent` - SO persistence
  `storage` - Persistence storage

### Method Detail

#### getName

    public String getName()

Return the name of the shared object.

Specified by:
  `getName` in interface `IPersistable`
Specified by:
  `getName` in interface `ISharedObjectStatistics`
Returns:
  the name of the shared object

#### setName

    public void setName(String name)

Set the name of the persistent object.

Specified by:
  `setName` in interface `IPersistable`
Parameters:
  `name` - New object name

#### getPath

    public String getPath()

Returns the path of the persistent object.

Specified by:
  `getPath` in interface `IPersistable`
Returns:
  Persisted object path

#### setPath

    public void setPath(String path)

Set the path of the persistent object.

Specified by:
  `setPath` in interface `IPersistable`
Parameters:
  `path` - New persisted object path

#### getType

    public String getType()

Returns the type of the persistent object.

Specified by:
  `getType` in interface `IPersistable`
Returns:
  Object type

#### getLastModified

    public long getLastModified()

Returns the timestamp when the object was last modified.

Specified by:
  `getLastModified` in interface `IPersistable`
Returns:
  Last modification date in milliseconds

#### isPersistent

    public boolean isPersistent()

Check if the shared object is persistent.

Specified by:
  `isPersistent` in interface `IPersistable`
Specified by:
  `isPersistent` in interface `ISharedObjectStatistics`
Returns:
  `True` if the shared object is persistent, otherwise `False`

#### setPersistent

    public void setPersistent(boolean persistent)

Set the persistent flag of the object.

Specified by:
  `setPersistent` in interface `IPersistable`
Parameters:
  `persistent` - `true` if object is persistent, `false` otherwise

#### sendUpdates

    protected void sendUpdates()

Send update notification over data channel of RTMP connection

#### notifyModified

    protected void notifyModified()

Send notification about modification of SO

#### returnError

    protected void returnError(String message)

Return an error message to the client.

Parameters:
  `message` -

#### returnAttributeValue

    protected void returnAttributeValue(String name)

Return an attribute value to the owner.

Parameters:
  `name` -

#### getAttribute

    public Object getAttribute(String name,
                      Object value)

Return attribute by name and set if it doesn't exist yet.

Specified by:
  `getAttribute` in interface `IAttributeStore`
Overrides:
  `getAttribute` in class `AttributeStore`
Parameters:
  `name` - Attribute name
  `value` - Value to set if attribute doesn't exist
Returns:
  Attribute value

#### setAttribute

    public boolean setAttribute(String name,
                       Object value)

Set value of attribute with given name

Specified by:
  `setAttribute` in interface `IAttributeStore`
Overrides:
  `setAttribute` in class `AttributeStore`
Parameters:
  `name` - Attribute name
  `value` - Attribute value
Returns:
  `true` if there's such attribute and value was set, `false` otherwise

#### setAttributes

    public void setAttributes(Map<String,Object> values)

Set attributes as map.

Specified by:
  `setAttributes` in interface `IAttributeStore`
Overrides:
  `setAttributes` in class `AttributeStore`
Parameters:
  `values` - Attributes.

#### setAttributes

    public void setAttributes(IAttributeStore values)

Set attributes as attributes store.

Specified by:
  `setAttributes` in interface `IAttributeStore`
Overrides:
  `setAttributes` in class `AttributeStore`
Parameters:
  `values` - Attributes.

#### removeAttribute

    public boolean removeAttribute(String name)

Removes attribute with given name

Specified by:
  `removeAttribute` in interface `IAttributeStore`
Specified by:
  `removeAttribute` in interface `AttributeStoreMXBean`
Overrides:
  `removeAttribute` in class `AttributeStore`
Parameters:
  `name` - Attribute
Returns:
  `true` if there's such an attribute and it was removed, `false` otherwise

#### sendMessage

    protected void sendMessage(String handler,
                   List<?> arguments)

Broadcast event to event handler

Parameters:
  `handler` - Event handler
  `arguments` - Arguments

#### getData

    public Map<String,Object> getData()

Getter for data.

Returns:
  SO data as unmodifiable map

#### getVersion

    public int getVersion()

Getter for version.

Specified by:
  `getVersion` in interface `ISharedObjectStatistics`
Returns:
  SO version.

#### removeAttributes

    public void removeAttributes()

Remove all attributes (clear Shared Object)

Specified by:
  `removeAttributes` in interface `IAttributeStore`
Specified by:
  `removeAttributes` in interface `AttributeStoreMXBean`
Overrides:
  `removeAttributes` in class `AttributeStore`

#### register

    protected void register(IEventListener listener)

Register event listener

Parameters:
  `listener` - Event listener

#### unregister

    protected void unregister(IEventListener listener)

Unregister event listener

Parameters:
  `listener` - Event listener

#### checkRelease

    protected void checkRelease()

Check if shared object must be released.

#### getListeners

    public Set<IEventListener> getListeners()

Get event listeners.

Returns:
  Value for property 'listeners'.

#### beginUpdate

    protected void beginUpdate()

Begin update of this Shared Object. Increases number of pending update operations

#### beginUpdate

    protected void beginUpdate(IEventListener listener)

Begin update of this Shared Object and setting listener

Parameters:
  `listener` - Update with listener

#### endUpdate

    protected void endUpdate()

End update of this Shared Object. Decreases number of pending update operations and broadcasts modified event if it is equal to zero (i.e. no more pending update operations).

#### serialize

    public void serialize(Output output)
                   throws IOException

Write the object to the passed output stream.

Specified by:
  `serialize` in interface `IPersistable`
Parameters:
  `output` - Output stream to write to
Throws:
  `IOException` - Any I/O exception

#### deserialize

    public void deserialize(Input input)
                     throws IOException

Load the object from the passed input stream.

Specified by:
  `deserialize` in interface `IPersistable`
Parameters:
  `input` - Input stream to load from
Throws:
  `IOException` - Any I/O exception

#### setStore

    public void setStore(IPersistenceStore store)

Store a reference to the persistence store in the object.

Specified by:
  `setStore` in interface `IPersistable`
Parameters:
  `store` - Store the object is saved in

#### getStore

    public IPersistenceStore getStore()

Returns the persistence store this object is stored in

Specified by:
  `getStore` in interface `IPersistable`
Returns:
  This object's persistence store

#### clear

    protected boolean clear()

Deletes all the attributes and sends a clear event to all listeners. The persistent data object is also removed from a persistent shared object.

Returns:
  `true` on success, `false` otherwise

#### close

    protected void close()

Detaches a reference from this shared object, reset it's state, this will destroy the reference immediately. This is useful when you don't want to proxy a shared object any longer.

#### acquire

    public void acquire()

Prevent shared object from being released. Each call to `acquire` must be paired with a call to `release` so the SO isn't held forever. This is only valid for non-persistent SOs.

#### isAcquired

    public boolean isAcquired()

Check if shared object currently is acquired.

Returns:
  `true` if the SO is acquired, otherwise `false`

#### release

    public void release()

Release previously acquired shared object. If the SO is non-persistent, no more clients are connected the SO isn't acquired any more, the data is released.

#### getCreationTime

    public long getCreationTime()

Return the timestamp the object was created.

Specified by:
  `getCreationTime` in interface `IStatisticsBase`
Returns:
  the timestamp in milliseconds since midnight, January 1, 1970 UTC.

#### getTotalListeners

    public int getTotalListeners()

Return total number of subscribed listeners.

Specified by:
  `getTotalListeners` in interface `ISharedObjectStatistics`
Returns:
  number of listeners

#### getMaxListeners

    public int getMaxListeners()

Return maximum number of concurrent subscribed listenes.

Specified by:
  `getMaxListeners` in interface `ISharedObjectStatistics`
Returns:
  number of listeners

#### getActiveListeners

    public int getActiveListeners()

Return current number of subscribed listeners.

Specified by:
  `getActiveListeners` in interface `ISharedObjectStatistics`
Returns:
  number of listeners

#### getTotalChanges

    public int getTotalChanges()

Return number of attribute changes.

Specified by:
  `getTotalChanges` in interface `ISharedObjectStatistics`
Returns:
  number of changes

#### getTotalDeletes

    public int getTotalDeletes()

Return number of attribute deletes.

Specified by:
  `getTotalDeletes` in interface `ISharedObjectStatistics`
Returns:
  number of deletes

#### getTotalSends

    public int getTotalSends()

Return number of times a message was sent.

Specified by:
  `getTotalSends` in interface `ISharedObjectStatistics`
Returns:
  number of sends