public final class AppLib
extends java.lang.Object
implements java.lang.Runnable
Client side for the API protocol.
The module lifecycle is controlled through start()
and stop()
.
Even though AppLib
implements Runnable
,
the use of it is deprecated and only exists for backwards compatibility.
The lifecycle methods should be used instead.
Lifecycle method contract (start()
, stop()
,
connect()
) is as follows:
Modifier and Type | Class and Description |
---|---|
static class |
AppLib.Builder
Builder for constructing
AppLib instances. |
static class |
AppLib.LifecycleStateViolationException
If a call to a method violates the lifecycle contract.
|
static class |
AppLib.State
Lifecycle state of the
AppLib . |
Modifier and Type | Field and Description |
---|---|
static long |
API_MAGIC
API protocol magic
|
static int |
API_V_MAJOR
API protocol major version
|
static int |
API_V_MINOR
API protocol minor version
|
static long |
DEFAULT_KEEPALIVE_INTERVAL
Default keepalive interval for sending in milliseconds (5000L).
|
static int |
DEFAULT_PORT |
static int |
WRITER_TASK_QUEUE_SIZE
Queue size for the writer tasks.
|
Constructor and Description |
---|
AppLib()
Deprecated.
use
builder() instead. |
AppLib(int port)
Deprecated.
use
builder() instead. |
Modifier and Type | Method and Description |
---|---|
void |
addHostDiscoveryCallback(HostDiscoveryCallback callback)
Adds a callback to be invoked when a peer has been discovered or the
discovery information has been updated.
|
void |
addLifecycleListener(AppLibLifecycleListener listener)
Adds a lifecycle listener that gets informed about changes in the AppLib
lifecycle.
|
void |
addListener(AppLibListener listener)
Deprecated.
Use
addLifecycleListener(fi.tkk.netlab.dtn.scampi.applib.AppLibLifecycleListener) for life cycle updates
(onConnected, etc.). |
void |
addLocationUpdateCallback(LocationUpdateCallback callback)
Adds a callback to be invoked when the API server updates the
(geographic) location of the node.
|
void |
addMessageReceivedCallback(MessageReceivedCallback callback)
Callback invoked for all messages that are published to any service
subscribe(java.lang.String) d to by this AppLib instance. |
void |
addMessageReceivedCallback(java.lang.String service,
MessageReceivedCallback callback)
Adds a callback when messages destined to the given service are received.
|
static AppLib.Builder |
builder()
Returns a builder instance to generate a new AppLib instance.
|
void |
connect()
Attempts to connect the
AppLib to a local SCAMPI API server. |
void |
delete(java.lang.String appTag)
Deletes the message with the given appTag from the router.
|
AppLib.State |
getLifecycleState()
Returns the lifecycle state for the instance.
|
java.lang.String |
getLocalID()
Returns the local SCAMPI ID of the router this API client is connected
to.
|
void |
publish(SCAMPIMessage message,
java.lang.String service)
Publishes a
SCAMPIMessage to the given service. |
void |
publish(SCAMPIMessage message,
java.lang.String service,
PublishDoneCallback callback)
Publishes a
SCAMPIMessage to the given service. |
void |
removeAllListeners()
Deprecated.
|
void |
removeHostDiscoveryCallback(HostDiscoveryCallback callback)
Remove a previously added callback.
|
void |
removeLifecycleListener(AppLibLifecycleListener listener)
Removes a previously added listener.
|
void |
removeListener(AppLibListener listener)
Deprecated.
|
void |
removeLocationUpdateCallback(LocationUpdateCallback callback)
Removes a previously added callback.
|
void |
removeMessageReceivedCallback(MessageReceivedCallback callback)
Removes a callback previously added by
addMessageReceivedCallback(
MessageReceivedCallback) . |
void |
removeMessageReceivedCallback(java.lang.String service,
MessageReceivedCallback callback)
Removes a callback previously added by
addMessageReceivedCallback(
String, MessageReceivedCallback) . |
void |
run()
Deprecated.
This is left for backwards compatibility. Now the
AppLib should be controlled through the lifecycle interface. |
void |
start()
Starts the instance.
|
void |
startHostDiscovery()
Starts receiving host discovery notifications.
|
void |
startHostDiscovery(HostDiscoveryCallback callback)
Starts receiving host discovery notifications through the given callback.
|
void |
startLocationUpdates()
Starts receiving location updates from the Scampi instance.
|
void |
startLocationUpdates(LocationUpdateCallback callback)
Equivalent to calling
addLocationUpdateCallback(
LocationUpdateCallback) followed by startLocationUpdates() . |
void |
startMapTileUpdates(MapTileUpdateCallback callback)
Starts receiving map tiles notifications through the given callback.
|
void |
stop()
Stops the
AppLib instance. |
void |
stopHostDiscovery()
Stops receiving host discovery notifications.
|
void |
stopLocationUpdates()
Stops receiving location updates.
|
void |
subscribe(java.lang.String service)
Subscribe to the given service.
|
void |
subscribe(java.lang.String service,
MessageReceivedCallback callback)
Equivalent to calling
addMessageReceivedCallback(String,
MessageReceivedCallback) followed by
subscribe(String) . |
public static final int DEFAULT_PORT
public static final int WRITER_TASK_QUEUE_SIZE
public static final long API_MAGIC
public static final int API_V_MAJOR
public static final int API_V_MINOR
public static final long DEFAULT_KEEPALIVE_INTERVAL
@Deprecated public AppLib()
builder()
instead.@Deprecated public AppLib(int port)
builder()
instead.port
- port where the API server is running.public final void addLifecycleListener(AppLibLifecycleListener listener)
listener
- listener to invokepublic final void removeLifecycleListener(AppLibLifecycleListener listener)
listener
- the listener to removepublic final void addMessageReceivedCallback(java.lang.String service, MessageReceivedCallback callback)
subscribe(java.lang.String)
.service
- service for which to invoke the callbackcallback
- callback to invokepublic final void removeMessageReceivedCallback(java.lang.String service, MessageReceivedCallback callback)
addMessageReceivedCallback(
String, MessageReceivedCallback)
. Not that this does not un-subscribe
from the service, just removes the callback.service
- the service from which to remove the callbackcallback
- the callback to removepublic final void addMessageReceivedCallback(MessageReceivedCallback callback)
subscribe(java.lang.String)
d to by this AppLib
instance.callback
- the callback to invokepublic final void removeMessageReceivedCallback(MessageReceivedCallback callback)
addMessageReceivedCallback(
MessageReceivedCallback)
. Note that this will not remove callbacks
added with addMessageReceivedCallback(String,
MessageReceivedCallback)
, use removeMessageReceivedCallback(
String, MessageReceivedCallback)
instead.callback
- callback to removepublic final void addLocationUpdateCallback(LocationUpdateCallback callback)
callback
- the callback to invokepublic final void removeLocationUpdateCallback(LocationUpdateCallback callback)
callback
- the callback to removepublic final void addHostDiscoveryCallback(HostDiscoveryCallback callback)
startHostDiscovery()
to start receiving discovery callbacks.callback
- the callback to invokepublic final void removeHostDiscoveryCallback(HostDiscoveryCallback callback)
callback
- the callback to removepublic final void subscribe(java.lang.String service) throws java.lang.InterruptedException
messageReceived()
callbacks when the router
receives messages published to the service. If subscribe is called
multiple times for the same service, each call results in the
registered MessageReceivedCallback
s getting invoked for all
messages published to the service currently carried by the Scampi
instance.service
- Service to subscribe to.java.lang.InterruptedException
public final void subscribe(java.lang.String service, MessageReceivedCallback callback) throws java.lang.InterruptedException
addMessageReceivedCallback(String,
MessageReceivedCallback)
followed by
subscribe(String)
.service
- the service to subscribe tocallback
- the callback to invoke for messages received from the
servicejava.lang.InterruptedException
public final void publish(SCAMPIMessage message, java.lang.String service) throws java.lang.InterruptedException
SCAMPIMessage
to the given service.message
- message to publish.service
- service to publish to.java.lang.InterruptedException
public final void publish(SCAMPIMessage message, java.lang.String service, PublishDoneCallback callback) throws java.lang.InterruptedException
SCAMPIMessage
to the given service. It is not safe
to modify the message
until the callback has been invoked. If
the AppLib
is in CONNECTED state the message will be sent to the
API server, otherwise if the state is IDLE the message will be buffered
and sent to the API server when entering CONNECTED state next time.message
- message to publish.service
- service to publish to.callback
- callback to be called once the publish operation has
completedjava.lang.IllegalStateException
- if the AppLib is not in CONNECTED or IDLE
state.java.lang.InterruptedException
public final void delete(java.lang.String appTag) throws java.lang.InterruptedException
appTag
- appTag of the message to deletejava.lang.InterruptedException
public final void startHostDiscovery() throws java.lang.InterruptedException
java.lang.InterruptedException
public final void startHostDiscovery(HostDiscoveryCallback callback) throws java.lang.InterruptedException
callback
- Callback for host discovery notifications.java.lang.InterruptedException
public final void stopHostDiscovery() throws java.lang.InterruptedException
java.lang.InterruptedException
public final void startLocationUpdates() throws java.lang.InterruptedException
java.lang.InterruptedException
- if the call blocked due to the API link
being congested and was interruptedpublic final void startLocationUpdates(LocationUpdateCallback callback) throws java.lang.InterruptedException
addLocationUpdateCallback(
LocationUpdateCallback)
followed by startLocationUpdates()
.callback
- Callback for location notifications.java.lang.InterruptedException
public final void stopLocationUpdates() throws java.lang.InterruptedException
java.lang.InterruptedException
- if the call blocked due to the API link
being congested and was interruptedpublic final void startMapTileUpdates(MapTileUpdateCallback callback) throws java.lang.InterruptedException
callback
- Callback for map tiles notifications.java.lang.UnsupportedOperationException
- not implemented in the current
version.java.lang.InterruptedException
public final java.lang.String getLocalID()
null
if the AppLib has
not connected yet.@Deprecated public void addListener(AppLibListener listener)
addLifecycleListener(fi.tkk.netlab.dtn.scampi.applib.AppLibLifecycleListener)
for life cycle updates
(onConnected, etc.).listener
- listener to add@Deprecated public void removeListener(AppLibListener listener)
@Deprecated public void removeAllListeners()
public static AppLib.Builder builder()
public final void start()
java.lang.IllegalStateException
- if the instance is not in NEW state.public final void stop()
AppLib
instance. The instance cannot be reused or
restarted after stop()
has been called.java.lang.IllegalStateException
- if the state is NEW or TERMINATED.public final void connect()
AppLib
to a local SCAMPI API server.java.lang.IllegalStateException
- if the call violates the lifecycle contract.public final AppLib.State getLifecycleState()
@Deprecated public void run()
AppLib
should be controlled through the lifecycle interface.run
in interface java.lang.Runnable