org.openbase.jul.pattern

Interface Remote<M>

Type Parameters:

M - the data type of the remote

All Superinterfaces:

Activatable, DataProvider<M>, Lockable, PingProvider, Shutdownable

All Known Subinterfaces:

ConfigurableRemote<ID,M,CONFIG>, IdentifiableRemote<ID,M>

public interface Remote<M>
extends Shutdownable, Activatable, Lockable, PingProvider, DataProvider<M>

Author:

Divine Threepwood

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Remote.ConnectionState

Nested classes/interfaces inherited from interface org.openbase.jul.iface.Shutdownable

Shutdownable.ShutdownDeamon

Method Summary

Modifier and Type	Method and Description
void	activate(boolean waitForData) Method activates the remote instance and blocks until the first data synchronization is done.
void	activate(Object maintainer) Atomic activate which makes sure that the maintainer stays the same.
void	addConnectionStateObserver(Observer<Remote.ConnectionState> observer) This method allows the registration of connection state observers to get informed about connection state changes.
Remote.ConnectionState	getConnectionState() Method returns the current connection state between this remote and its main controller.
M	getData() Method returns the data object of this remote which is synchronized with the server data in background.
Class<M>	getDataClass() Method returns the class of the data object.
default CompletableFuture<M>	getDataFuture() Returns a future of the data object.
Long	getPing() Method returns the result of the latest connection ping between this remote and its main controller.
boolean	isConnected() Checks if a server connection is established.
Future<Long>	ping() Method triggers a ping between this remote and its main controller and returns the calculated connection delay.
void	removeConnectionStateObserver(Observer<Remote.ConnectionState> observer) This method removes already registered connection state observers.
CompletableFuture<M>	requestData() This method synchronizes this remote instance with the main controller and returns the new data object.
void	waitForConnectionState(Remote.ConnectionState connectionState, long timeout) Method blocks until the remote reaches the desired connection state.
void	waitForData() Method blocks until an initial data message was received from the remote controller.
void	waitForData(long timeout, TimeUnit timeUnit) Method blocks until an initial data message was received from the main controller or the given timeout is reached.

Methods inherited from interface org.openbase.jul.iface.Shutdownable

registerShutdownHook, registerShutdownHook, shutdown

Methods inherited from interface org.openbase.jul.iface.Activatable

activate, deactivate, isActive

Methods inherited from interface org.openbase.jul.iface.Lockable

isLocked, lock, unlock, verifyMaintainability

Methods inherited from interface org.openbase.jul.pattern.provider.DataProvider

addDataObserver, isDataAvailable, removeDataObserver

Method Detail

activate

void activate(boolean waitForData)
       throws CouldNotPerformException,
              InterruptedException

Method activates the remote instance and blocks until the first data synchronization is done. Equivalent of: activate(); waitForData(0); Caution: Method can blocks forever if the related main controller instance will be never available!

Parameters:

waitForData - if this flag is true the method will block until the first data synchronization is done.

Throws:

CouldNotPerformException - if the activation could not be performed

InterruptedException - if the activation is interrupted

activate

void activate(Object maintainer)
       throws InterruptedException,
              CouldNotPerformException

Atomic activate which makes sure that the maintainer stays the same. This method just locks the remote with the given maintainer after activation if it was never locked before.

Parameters:

maintainer - the current maintainer of this remote

Throws:

InterruptedException - if activation is interrupted

CouldNotPerformException - if activation fails

addConnectionStateObserver

void addConnectionStateObserver(Observer<Remote.ConnectionState> observer)

This method allows the registration of connection state observers to get informed about connection state changes.

Parameters:

observer - the observer added

removeConnectionStateObserver

void removeConnectionStateObserver(Observer<Remote.ConnectionState> observer)

This method removes already registered connection state observers.

Parameters:

observer - the observer removed

getDataClass

Class<M> getDataClass()

Method returns the class of the data object.

Specified by:

getDataClass in interface DataProvider<M>

Returns:

the class of the data object

getData

M getData()
   throws NotAvailableException

Method returns the data object of this remote which is synchronized with the server data in background. In case the data was never received not available a NotAvailableException is thrown. Use method getDataFuture() to get feedback about the synchronization state, or use method waitForData() to block until the needed data is synchronized.

Specified by:

getData in interface DataProvider<M>

Returns:

the data object of the remote.

Throws:

NotAvailableException - is thrown in case the data is not yet synchronized with the main controller instance.

getDataFuture

default CompletableFuture<M> getDataFuture()

Returns a future of the data object. This method can be useful after remote initialization in case the data object was not received jet. The future can be used to wait for the data object.

Specified by:

getDataFuture in interface DataProvider<M>

Returns:

a future object delivering the data if available.

waitForData

void waitForData()
          throws CouldNotPerformException,
                 InterruptedException

Method blocks until an initial data message was received from the remote controller.

Specified by:

waitForData in interface DataProvider<M>

Throws:

CouldNotPerformException - is thrown if any error occurs.

InterruptedException - is thrown in case the thread is externally interrupted.

waitForData

void waitForData(long timeout,
                 TimeUnit timeUnit)
          throws CouldNotPerformException,
                 InterruptedException

Method blocks until an initial data message was received from the main controller or the given timeout is reached.

Specified by:

waitForData in interface DataProvider<M>

Parameters:

timeout - maximal time to wait for the main controller data. After the timeout is reached a NotAvailableException is thrown which is caused by a TimeoutException.

timeUnit - the time unit of the timeout.

Throws:

CouldNotPerformException - is thrown in case the any error occurs, or if the given timeout is reached. In this case a TimeoutException is thrown.

InterruptedException - is thrown in case the thread is externally interrupted.

isConnected

boolean isConnected()

Checks if a server connection is established.

Returns:

is true in case the connection is established.

getConnectionState

Remote.ConnectionState getConnectionState()

Method returns the current connection state between this remote and its main controller.

Returns:

the current connection state.

waitForConnectionState

void waitForConnectionState(Remote.ConnectionState connectionState,
                            long timeout)
                     throws InterruptedException,
                            TimeoutException,
                            CouldNotPerformException

Method blocks until the remote reaches the desired connection state. In case the timeout is expired an TimeoutException will be thrown.

Parameters:

connectionState - the desired connection state

timeout - the timeout in milliseconds until the method throw a TimeoutException in case the connection state was not reached.

Throws:

InterruptedException - is thrown in case the thread is externally interrupted.

TimeoutException - is thrown in case the timeout is expired without reaching the connection state.

CouldNotPerformException - is thrown in case the connection state does not match and the shutdown of this remote has been initialized

requestData

CompletableFuture<M> requestData()
                          throws CouldNotPerformException

This method synchronizes this remote instance with the main controller and returns the new data object. Normally, all server data changes are automatically synchronized to all remote instances. In case you have triggered many server changes, this changes are sequentially applied. With this method you can force the sync to get instantly a data object with all applied changes. This action can not be canceled! Use this method with caution because high frequently calls will reduce the network performance! The preferred by to access the data object

Returns:

A CompletableFuture which gives feedback about the successful synchronization.

Throws:

CouldNotPerformException - In case the sync could not be triggered an CouldNotPerformException will be thrown.

ping

Future<Long> ping()

Method triggers a ping between this remote and its main controller and returns the calculated connection delay. This method is triggered automatically in background to check if the main controller is still available.

Specified by:

ping in interface PingProvider

Returns:

the connection delay in milliseconds.

getPing

Long getPing()

Method returns the result of the latest connection ping between this remote and its main controller.

Specified by:

getPing in interface PingProvider

Returns:

the latest connection delay in milliseconds.