Package io.ably.lib.realtime

Class RealtimeAnnotations

java.lang.Object

io.ably.lib.realtime.RealtimeAnnotations

public class RealtimeAnnotations
extends Object

RealtimeAnnotation provides subscription capabilities for annotations received on a channel. It allows adding or removing listeners to handle annotation events and facilitates broadcasting those events to the appropriate listeners.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	RealtimeAnnotations.AnnotationListener

Constructor Summary

Constructors

Constructor	Description
RealtimeAnnotations(ChannelBase channel, RestAnnotations restAnnotations)

Method Summary

Modifier and Type	Method	Description
void	delete(Message message, Annotation annotation)	See delete(String, Annotation)
void	delete(Message message, Annotation annotation, CompletionListener listener)	See delete(String, Annotation, CompletionListener)
void	delete(String messageSerial, Annotation annotation)
void	delete(String messageSerial, Annotation annotation, CompletionListener listener)	Deletes an annotation associated with the specified message serial.
PaginatedResult<Annotation>	get(Message message)	See get(String)
PaginatedResult<Annotation>	get(Message message, Param[] params)	See get(String, Param[])
PaginatedResult<Annotation>	get(String messageSerial)	Retrieves a paginated list of annotations associated with the specified message serial.
PaginatedResult<Annotation>	get(String messageSerial, Param[] params)	Retrieves a paginated list of annotations associated with the specified message serial.
void	getAsync(Message message, Callback<AsyncPaginatedResult<Annotation>> callback)	See getAsync(String, Callback)
void	getAsync(Message message, Param[] params, Callback<AsyncPaginatedResult<Annotation>> callback)	See getAsync(String, Param[], Callback)
void	getAsync(String messageSerial, Callback<AsyncPaginatedResult<Annotation>> callback)	Asynchronously retrieves a paginated list of annotations associated with the specified message serial.
void	getAsync(String messageSerial, Param[] params, Callback<AsyncPaginatedResult<Annotation>> callback)	Asynchronously retrieves a paginated list of annotations associated with the specified message serial.
void	onAnnotation(ProtocolMessage protocolMessage)	Internal method.
void	publish(Message message, Annotation annotation)	See publish(String, Annotation)
void	publish(Message message, Annotation annotation, CompletionListener listener)	See publish(String, Annotation, CompletionListener)
void	publish(String messageSerial, Annotation annotation)	Publishes an annotation to the specified channel with the given message serial.
void	publish(String messageSerial, Annotation annotation, CompletionListener listener)	Publishes an annotation to the specified channel with the given message serial.
void	subscribe(RealtimeAnnotations.AnnotationListener listener)	Subscribes the given RealtimeAnnotations.AnnotationListener to the channel, allowing it to receive annotations.
void	subscribe(String type, RealtimeAnnotations.AnnotationListener listener)	Subscribes the given RealtimeAnnotations.AnnotationListener to the channel for a specific annotation type, allowing it to receive annotations of the specified type.
void	unsubscribe(RealtimeAnnotations.AnnotationListener listener)	Unsubscribes the specified RealtimeAnnotations.AnnotationListener from the channel, stopping it from receiving further annotations.
void	unsubscribe(String type, RealtimeAnnotations.AnnotationListener listener)	Unsubscribes the specified RealtimeAnnotations.AnnotationListener from receiving annotations of a particular type within the channel.

Methods inherited from class java.lang.Object

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

Constructor Details

RealtimeAnnotations

public RealtimeAnnotations(ChannelBase channel,
 RestAnnotations restAnnotations)

Method Details

publish

public void publish(String messageSerial,
 Annotation annotation,
 CompletionListener listener)
             throws AblyException

Publishes an annotation to the specified channel with the given message serial. Validates and encodes the annotation before sending it as a protocol message.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message to be annotated

annotation - the annotation object associated with the message

listener - the completion listener to handle success or failure during the publish process

Throws:

AblyException - if an error occurs during validation, encoding, or sending the annotation

publish

public void publish(Message message,
 Annotation annotation,
 CompletionListener listener)
             throws AblyException

See publish(String, Annotation, CompletionListener)

Throws:

AblyException

publish

public void publish(String messageSerial,
 Annotation annotation)
             throws AblyException

Publishes an annotation to the specified channel with the given message serial. Validates and encodes the annotation before sending it as a protocol message.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message to be annotated

annotation - the annotation object associated with the message

Throws:

AblyException - if an error occurs during validation, encoding, or sending the annotation

publish

public void publish(Message message,
 Annotation annotation)
             throws AblyException

See publish(String, Annotation)

Throws:

AblyException

delete

public void delete(String messageSerial,
 Annotation annotation,
 CompletionListener listener)
            throws AblyException

Deletes an annotation associated with the specified message serial. Sets the annotation action to `ANNOTATION_DELETE` and publishes the update to the channel with the given completion listener.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message being annotated

annotation - the annotation object to be deleted

listener - the completion listener to handle success or failure during the deletion process

Throws:

AblyException - if an error occurs during the deletion or publishing process

delete

public void delete(Message message,
 Annotation annotation,
 CompletionListener listener)
            throws AblyException

See delete(String, Annotation, CompletionListener)

Throws:

AblyException

delete

public void delete(String messageSerial,
 Annotation annotation)
            throws AblyException

Throws:

AblyException

delete

public void delete(Message message,
 Annotation annotation)
            throws AblyException

See delete(String, Annotation)

Throws:

AblyException

get

public PaginatedResult<Annotation> get(String messageSerial,
 Param[] params)
                                throws AblyException

Retrieves a paginated list of annotations associated with the specified message serial.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message being annotated.

params - an array of query parameters for filtering or modifying the request.

Returns:

a PaginatedResult containing the matching annotations.

Throws:

AblyException - if an error occurs during the retrieval process.

get

public PaginatedResult<Annotation> get(Message message,
 Param[] params)
                                throws AblyException

See get(String, Param[])

Throws:

AblyException

get

public PaginatedResult<Annotation> get(String messageSerial)
                                throws AblyException

Retrieves a paginated list of annotations associated with the specified message serial.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message being annotated

Returns:

a PaginatedResult containing the matching annotations

Throws:

AblyException - if an error occurs during the retrieval process

get

public PaginatedResult<Annotation> get(Message message)
                                throws AblyException

See get(String)

Throws:

AblyException

getAsync

public void getAsync(String messageSerial,
 Param[] params,
 Callback<AsyncPaginatedResult<Annotation>> callback)
              throws AblyException

Asynchronously retrieves a paginated list of annotations associated with the specified message serial.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message being annotated.

params - an array of query parameters for filtering or modifying the request.

callback - a callback to handle the result asynchronously, providing an AsyncPaginatedResult containing the matching annotations.

Throws:

AblyException

getAsync

public void getAsync(Message message,
 Param[] params,
 Callback<AsyncPaginatedResult<Annotation>> callback)
              throws AblyException

See getAsync(String, Param[], Callback)

Throws:

AblyException

getAsync

public void getAsync(String messageSerial,
 Callback<AsyncPaginatedResult<Annotation>> callback)
              throws AblyException

Asynchronously retrieves a paginated list of annotations associated with the specified message serial.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

messageSerial - the unique serial identifier for the message being annotated.

callback - a callback to handle the result asynchronously, providing an AsyncPaginatedResult containing the matching annotations.

Throws:

AblyException

getAsync

public void getAsync(Message message,
 Callback<AsyncPaginatedResult<Annotation>> callback)
              throws AblyException

See getAsync(String, Callback)

Throws:

AblyException

subscribe

public void subscribe(RealtimeAnnotations.AnnotationListener listener)
               throws AblyException

Subscribes the given RealtimeAnnotations.AnnotationListener to the channel, allowing it to receive annotations. If the channel's attach on subscribe option is enabled, the channel is attached automatically.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

listener - the listener to be subscribed to the channel

Throws:

AblyException - if an error occurs during channel attachment

unsubscribe

public void unsubscribe(RealtimeAnnotations.AnnotationListener listener)

Unsubscribes the specified RealtimeAnnotations.AnnotationListener from the channel, stopping it from receiving further annotations. Any corresponding type-specific listeners associated with the listener are also removed.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

listener - the RealtimeAnnotations.AnnotationListener to be unsubscribed

subscribe

public void subscribe(String type,
 RealtimeAnnotations.AnnotationListener listener)
               throws AblyException

Subscribes the given RealtimeAnnotations.AnnotationListener to the channel for a specific annotation type, allowing it to receive annotations of the specified type. If the channel's attach on subscribe option is enabled, the channel is attached automatically.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

type - the specific annotation type to subscribe to; if null, subscribes to all types

listener - the RealtimeAnnotations.AnnotationListener to be subscribed

Throws:

AblyException

unsubscribe

public void unsubscribe(String type,
 RealtimeAnnotations.AnnotationListener listener)

Unsubscribes the specified RealtimeAnnotations.AnnotationListener from receiving annotations of a particular type within the channel. If there are no remaining listeners for the specified type, the type-specific listener collection is also removed.

Note: This is an experimental API. While the underlying functionality is stable, the public API may change in future releases.

Parameters:

type - the specific annotation type to unsubscribe from; if null, unsubscribes from all annotations associated with the listener

listener - the RealtimeAnnotations.AnnotationListener to be unsubscribed

onAnnotation

public void onAnnotation(ProtocolMessage protocolMessage)

Internal method. Handles incoming annotation messages from the protocol layer.

Parameters:

protocolMessage - the protocol message containing annotation data