octoshape.osa2.android
Class OctoshapeSystem

java.lang.Object
  extended by octoshape.osa2.android.OctoshapeSystem

public class OctoshapeSystem
extends java.lang.Object

Represents the Octoshape system for Android.

The class can be in four states:

On construction, the class will be in sleeping state. Whenever in sleeping or operating state, the class can be brought to closing state by calling the close(Runnable) method, which will close the connection to the Octoshape Service. After this, the class will eventually switch to closed state indicated by the fact that the argument given to the close method will be called.

When the class is in sleeping state, one can call the open() method to bring it to operating state and start/connect to the Octoshape Service. The class will stay in operating state until either close(Runnable) is called or until it by itself decides to switch to sleeping state in which case it will call the callback set to the OctoshapeSystem#setProblemListener(ProblemListener) method.

This class should be considered singleton in the sense that one would never want to have more than one instance of this class which is not in closed state.

The class is thread safe, so it is safe to call its methods from any thread. No guarantee is made about which thread callback are called from. However, callbacks are expected to not block for any non-significant amount of time.

After constructing the OctoshapeSystem object, it is necessary to add at least one available media player using the addPlayerNameAndVersion(String, String, String) method. After that the open() method must be called. This will will make the OctoshapeSystem object start and try to establish a connection to the Octoshape Service.

It is possible to create and initialize StreamPlayer objects both before and after calling open(). Calling StreamPlayer.initialize(boolean) or StreamPlayer.requestPlay() on a StreamPlayer object before calling open, will make the it initialize, or request to play, immediately after a connection to the client is established.

Example: We want to make a user interface with 3 buttons, each launching a different octoshape stream, but where one of the streams should also start to play as soon as the interface loads. The recommended way to do this would be:

  1. Create the OctoshapeSystem object and add available media players
  2. Create all 3 StreamPlayer objects, and set ProblemListener, UrlListeners, SelectedPlayerListener, and other listeners on them.
  3. Create the 3 buttons so they call requestPlay() on the appropriate StreamPlayers
  4. Call requestPlay() on the main StreamPlayer
  5. Call initialize() on the other two StreamPlayers
  6. Call open() on the OctoshapeSystem
As soon as the OctoshapeSystem has a client connection, the main StreamPlayer will initialize and play at the same time, and the other StreamPlayers will initialize, so they are quick to play when the user pushes their buttons.


Field Summary
static java.lang.String ANDROID_AKAMAI_PLAYER
          Name constant for the Akamai Android AMP SDK.
static java.lang.String ANDROID_NEXSTREAMING_PLAYER
          Name constant for the NexStreaming media player for Android Constant used as name argument to addPlayerNameAndVersion(String, String, String).
static java.lang.String MEDIA_PLAYER_FLASH
          Name constant for the Flash Player on Android OS.
static java.lang.String MEDIA_PLAYER_NATIVE
          Name constant for the native media player on Android OS (android.media.MediaPlayer).
static java.lang.String MEDIA_PLAYER_VITAMIO
          Name constant for the Vitamio Player on Android OS.
 
Method Summary
 void addPlayerNameAndVersion(java.lang.String mediaPlayerId, java.lang.String mediaPlayerName, java.lang.String mediaPlayerVersion)
          Telling the OctoshapeSystem that we are capable of using this media player to play streams.
 StreamPlayer createStreamPlayer(java.lang.String link)
          Constructs a new StreamPlayer object.
 StreamPusher createStreamPusher(java.lang.String link, java.lang.String url, java.lang.String password)
          Constructs a new StreamPusher object capable of pushing a stream to Octoshape.
 int getHTTPTunnelSegmentBytes()
          Gets HTTP tunnel total bytes received.
 int getHTTPTunnelTotalBytes()
          Gets HTTP tunnel total bytes received.
 ProblemListener getProblemListener()
          Method returning the ProblemListener instance used by the OctoshapeSystem
 void open()
          Brings OctoshapeSystem to operating state and starts and connects to the Octoshape Service When called in sleeping state, this will switch the class into running state.
 java.lang.String openHTTPTunnel(java.lang.String domainsSeparatedByComma)
          Opens HTTP tunnels on several domains specifies as parameter.
 java.lang.String platformIdentificationInBase64()
          Returns relevant runtime and compile time information about a client's platform and build.
 void prepare(long sessionid, java.lang.String suffix)
          Call this to prepare the Octoshape system for streaming.
 void resetHTTPTunnelCounters()
          Reset all of the HTTP tunnel counters.
 void setOctoshapeSystemListener(OctoshapeSystemListener listener)
          Sets the listener that listens for information from the OctoshapeSystem.
 void setStartupListener(ProgressListener startupListener)
          Listens for progress events.
 java.lang.String version()
          Returns the version identifier of the Octoshape SDK.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MEDIA_PLAYER_FLASH

public static final java.lang.String MEDIA_PLAYER_FLASH
Name constant for the Flash Player on Android OS.

Constant used as name argument to addPlayerNameAndVersion(String, String, String). The version of the player should be set to PackageInfo.versionName for the Flash app.

See Also:
Constant Field Values

MEDIA_PLAYER_VITAMIO

public static final java.lang.String MEDIA_PLAYER_VITAMIO
Name constant for the Vitamio Player on Android OS.

Constant used as name argument to addPlayerNameAndVersion(String, String, String). The version of the player should be set to PackageInfo.versionName for the Flash app.

See Also:
Constant Field Values

MEDIA_PLAYER_NATIVE

public static final java.lang.String MEDIA_PLAYER_NATIVE
Name constant for the native media player on Android OS (android.media.MediaPlayer).

Constant used as name argument to addPlayerNameAndVersion(String, String, String). The version of the player should be set to the value of the vitamio SDK version.

See Also:
Constant Field Values

ANDROID_NEXSTREAMING_PLAYER

public static final java.lang.String ANDROID_NEXSTREAMING_PLAYER
Name constant for the NexStreaming media player for Android

Constant used as name argument to addPlayerNameAndVersion(String, String, String). The version of the player should be set to the value of the NexStreaming SDK version.

See Also:
Constant Field Values

ANDROID_AKAMAI_PLAYER

public static final java.lang.String ANDROID_AKAMAI_PLAYER
Name constant for the Akamai Android AMP SDK.

Constant used as name argument to addPlayerNameAndVersion(String, String, String). The version of the player should be set to the value of the NexStreaming SDK version.

See Also:
Constant Field Values
Method Detail

getProblemListener

public ProblemListener getProblemListener()
Method returning the ProblemListener instance used by the OctoshapeSystem

Returns:
problemListener

createStreamPlayer

public StreamPlayer createStreamPlayer(java.lang.String link)
Constructs a new StreamPlayer object.

Subsequently call one of the StreamPlayer.requestPlay(..) method to start playing.

It is recommended to set appropriate listeners on the returned object before calling any play methods.

Parameters:
link - The octo-link uniquely identifying the stream in the Octoshape system.
Returns:
a new StreamPlayer object.

open

public void open()
Brings OctoshapeSystem to operating state and starts and connects to the Octoshape Service

When called in sleeping state, this will switch the class into running state. Calling this method in a non-sleeping state is a null operation.

If a requestPlay method have been called on a StreamPlayer before calling this method, or after it has been called, but before a connection has been established, then that StreamPlayer will begin to play as soon as a connection has been made. The same is true for calls to StreamPlayer.initialize().

All listers for the OctoshapeSystem must be set before calling open().


setStartupListener

public void setStartupListener(ProgressListener startupListener)
Listens for progress events.

This may be called while the class is in operating state. It will typically be called with a 0 argument whenever the class tries to establish a connection to an Octoshape client and will be called with a 1000 argument whenever it is does not try to do that anymore.

It is guaranteed, that whenever the listener has been called with a permille different from 1000 then it will subsequently be called with 1000.

Setting a ProgressListener removes any previously set listener. If called with null argument this will remove any previously set listener.

Must be called before calling open().

Parameters:
startupListener -

setOctoshapeSystemListener

public void setOctoshapeSystemListener(OctoshapeSystemListener listener)
Sets the listener that listens for information from the OctoshapeSystem.

Setting an OctoshapeSystemListener removes any previously set listener. If called with null argument this will remove any previously set listener.

Must be called before calling open().

Parameters:
listener -

addPlayerNameAndVersion

public void addPlayerNameAndVersion(java.lang.String mediaPlayerId,
                                    java.lang.String mediaPlayerName,
                                    java.lang.String mediaPlayerVersion)
Telling the OctoshapeSystem that we are capable of using this media player to play streams.

Can be called multiple times to supply a list of available players. Must be called before calling initialize or requestPlay on any StreamPlayers.

For each StreamPlayer the Octoshape client will select the most suitable media player. The result is given to the StreamPlayerListener set using the StreamPlayer#setListener(octoshape.osa2.listeners.StreamPlayerListener) method.

Please use either one of the MEDIA_PLAYER_.. constants as name and set the version as described in the documentation of that constant. In case the media player is not defined as one of the MEDIA_PLAYER_.. constants, then or contact Octoshape to find an appropriate value to use.

(If only media players that are not known to the client is added, then the client will choose one in the list at random and reply that in the StreamPlayerListener.resolvedOsaSeek(boolean, long, String) method. In this case osa-seek may or may not work correctly).

Parameters:
mediaPlayerId - The unique id that will be reported back to the StreamPlayerListener, if this media player is selected.
mediaPlayerName - The name of the media player. May be one of the MEDIA_PLAYER_.. constants.
mediaPlayerVersion - The version of the media player.

createStreamPusher

public StreamPusher createStreamPusher(java.lang.String link,
                                       java.lang.String url,
                                       java.lang.String password)
Constructs a new StreamPusher object capable of pushing a stream to Octoshape.

Note that the stream (i.e. the Octolink) must be already be set up in the Octoshape back-end system.

Subsequently call the StreamPusher.initialize() method to start pushing.

It is recommended to set appropriate listeners on the returned object before calling the initialize method.

Parameters:
link - The octo-link uniquely identifying the stream in the Octoshape system.
url - The media source URL.
password - The push password the stream is configured to have in the Octoshape system, or null if it has no password.
Returns:
a new StreamPusher object.

version

public java.lang.String version()
Returns the version identifier of the Octoshape SDK.


platformIdentificationInBase64

public java.lang.String platformIdentificationInBase64()
Returns relevant runtime and compile time information about a client's platform and build. This is intended to be used on a client, and then sent over the wire to servers that might have an use for this information.

Please note that this method is not intended to be invoked at all for ordinary usage of the SDK.


openHTTPTunnel

public java.lang.String openHTTPTunnel(java.lang.String domainsSeparatedByComma)
Opens HTTP tunnels on several domains specifies as parameter.

Parameters:
domainsSeparatedByComma - is a set of domains separated by commas.
Returns:
an array of EndPoints

getHTTPTunnelTotalBytes

public int getHTTPTunnelTotalBytes()
Gets HTTP tunnel total bytes received.


getHTTPTunnelSegmentBytes

public int getHTTPTunnelSegmentBytes()
Gets HTTP tunnel total bytes received.

Returns:
number of total bytes received - 0 if no tunnel has been opened yet.

resetHTTPTunnelCounters

public void resetHTTPTunnelCounters()
Reset all of the HTTP tunnel counters.


prepare

public void prepare(long sessionid,
                    java.lang.String suffix)
Call this to prepare the Octoshape system for streaming.

It is not necessary to call this, but it may speed up later streaming requests. It is recommended to call this once and as soon as possible once the OctoshapePortListener:onPortBound(java.lang.String, int) callback was received. Calling this function prior to receiving a OctoshapePortListener:onPortBound(java.lang.String, int) does not have any effect.

This feature MUST NOT be used, except when especially instructed by Octoshape. Octoshape will then provide details on which arguments should be used.

Parameters:
sessionid - Some session id
suffix - The encoded string containing the player type and Octoshape stream name prefix