io.aeron

Class Publication

java.lang.Object

io.aeron.Publication

All Implemented Interfaces:

java.lang.AutoCloseable

public class Publication
extends java.lang.Object
implements java.lang.AutoCloseable

Aeron Publisher API for sending messages to subscribers of a given channel and streamId pair. Publications are created via the Aeron.addPublication(String, int) method, and messages are sent via one of the offer(DirectBuffer) methods, or a tryClaim(int, BufferClaim) and BufferClaim.commit() method combination. The APIs used try claim and offer are non-blocking. Note: Publication instances are threadsafe and can be shared between publishing threads.

See Also:

Aeron.addPublication(String, int), BufferClaim

Field Summary

Fields

Modifier and Type	Field and Description
static long	ADMIN_ACTION The offer failed due to an administration action and should be retried.
static long	BACK_PRESSURED The offer failed due to back pressure from the subscribers preventing further transmission.
static long	CLOSED The Publication has been closed and should no longer be used.
static long	NOT_CONNECTED The publication is not yet connected to a subscriber.

Method Summary

Modifier and Type	Method and Description
void	addDestination(java.lang.String endpointChannel) Add a destination manually to a multi-destination-cast Publication.
java.lang.String	channel() Media address for delivery to the channel.
void	close() Release resources used by this Publication when there are no more references.
int	initialTermId() The initial term id assigned when this Publication was created.
boolean	isClosed() Has this object been closed and should no longer be used?
boolean	isConnected() Has the Publication seen an active Subscriber recently?
int	maxMessageLength() Maximum message length supported in bytes.
int	maxPayloadLength() Maximum length of a message payload that fits within a message fragment.
long	offer(org.agrona.DirectBuffer buffer) Non-blocking publish of a buffer containing a message.
long	offer(org.agrona.DirectBuffer buffer, int offset, int length) Non-blocking publish of a partial buffer containing a message.
long	offer(org.agrona.DirectBuffer buffer, int offset, int length, ReservedValueSupplier reservedValueSupplier) Non-blocking publish of a partial buffer containing a message.
long	position() Get the current position to which the publication has advanced for this stream.
long	positionLimit() Get the position limit beyond which this Publication will be back pressured.
long	registrationId() Return the registration id used to register this Publication with the media driver.
void	removeDestination(java.lang.String endpointChannel) Remove a previously added destination manually from a multi-destination-cast Publication.
int	sessionId() Session under which messages are published.
int	streamId() Stream identity for scoping within the channel media address.
int	termBufferLength() Get the length in bytes for each term partition in the log buffer.
long	tryClaim(int length, BufferClaim bufferClaim) Try to claim a range in the publication log into which a message can be written with zero copy semantics.

Methods inherited from class java.lang.Object

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

Field Detail

NOT_CONNECTED

public static final long NOT_CONNECTED

The publication is not yet connected to a subscriber.

See Also:

Constant Field Values

BACK_PRESSURED

public static final long BACK_PRESSURED

The offer failed due to back pressure from the subscribers preventing further transmission.

See Also:

Constant Field Values

ADMIN_ACTION

public static final long ADMIN_ACTION

The offer failed due to an administration action and should be retried.

See Also:

Constant Field Values

CLOSED

public static final long CLOSED

The Publication has been closed and should no longer be used.

See Also:

Constant Field Values

Method Detail

termBufferLength

public int termBufferLength()

Get the length in bytes for each term partition in the log buffer.

Returns:

the length in bytes for each term partition in the log buffer.

channel

public java.lang.String channel()

Media address for delivery to the channel.

Returns:

Media address for delivery to the channel.

streamId

public int streamId()

Stream identity for scoping within the channel media address.

Returns:

Stream identity for scoping within the channel media address.

sessionId

public int sessionId()

Session under which messages are published. Identifies this Publication instance.

Returns:

the session id for this publication.

initialTermId

public int initialTermId()

The initial term id assigned when this Publication was created. This can be used to determine how many terms have passed since creation.

Returns:

the initial term id.

maxMessageLength

public int maxMessageLength()

Maximum message length supported in bytes. Messages may be made of multiple fragments if greater than MTU length.

Returns:

maximum message length supported in bytes.

maxPayloadLength

public int maxPayloadLength()

Maximum length of a message payload that fits within a message fragment. This is he MTU length minus the message fragment header length.

Returns:

maximum message fragment payload length.

registrationId

public long registrationId()

Return the registration id used to register this Publication with the media driver.

Returns:

registration id

isConnected

public boolean isConnected()

Has the Publication seen an active Subscriber recently?

Returns:

true if this Publication has seen an active subscriber otherwise false.

close

public void close()

Release resources used by this Publication when there are no more references. Publications are reference counted and are only truly closed when the ref count reaches zero.

Specified by:

close in interface java.lang.AutoCloseable

isClosed

public boolean isClosed()

Has this object been closed and should no longer be used?

Returns:

true if it has been closed otherwise false.

position

public long position()

Get the current position to which the publication has advanced for this stream.

Returns:

the current position to which the publication has advanced for this stream.

Throws:

java.lang.IllegalStateException - if the publication is closed.

positionLimit

public long positionLimit()

Get the position limit beyond which this Publication will be back pressured. This should only be used as a guide to determine when back pressure is likely to be applied.

Returns:

the position limit beyond which this Publication will be back pressured.

offer

public long offer(org.agrona.DirectBuffer buffer)

Non-blocking publish of a buffer containing a message.

Parameters:

buffer - containing message.

Returns:

The new stream position, otherwise NOT_CONNECTED, BACK_PRESSURED, ADMIN_ACTION, or CLOSED.

offer

public long offer(org.agrona.DirectBuffer buffer,
                  int offset,
                  int length)

Non-blocking publish of a partial buffer containing a message.

Parameters:

buffer - containing message.

offset - offset in the buffer at which the encoded message begins.

length - in bytes of the encoded message.

Returns:

The new stream position, otherwise a negative error value NOT_CONNECTED, BACK_PRESSURED, ADMIN_ACTION, or CLOSED.

offer

public long offer(org.agrona.DirectBuffer buffer,
                  int offset,
                  int length,
                  ReservedValueSupplier reservedValueSupplier)

Non-blocking publish of a partial buffer containing a message.

Parameters:

buffer - containing message.

offset - offset in the buffer at which the encoded message begins.

length - in bytes of the encoded message.

reservedValueSupplier - ReservedValueSupplier for the frame.

Returns:

The new stream position, otherwise a negative error value NOT_CONNECTED, BACK_PRESSURED, ADMIN_ACTION, or CLOSED.

tryClaim

public long tryClaim(int length,
                     BufferClaim bufferClaim)

Try to claim a range in the publication log into which a message can be written with zero copy semantics. Once the message has been written then BufferClaim.commit() should be called thus making it available. Note: This method can only be used for message lengths less than MTU length minus header.

     final BufferClaim bufferClaim = new BufferClaim(); // Can be stored and reused to avoid allocation

     if (publication.tryClaim(messageLength, bufferClaim) > 0L)
     {
         try
         {
              final MutableDirectBuffer buffer = bufferClaim.buffer();
              final int offset = bufferClaim.offset();

              // Work with buffer directly or wrap with a flyweight
         }
         finally
         {
             bufferClaim.commit();
         }
     }
 

Parameters:

length - of the range to claim, in bytes..

bufferClaim - to be populated if the claim succeeds.

Returns:

The new stream position, otherwise NOT_CONNECTED, BACK_PRESSURED, ADMIN_ACTION, or CLOSED.

Throws:

java.lang.IllegalArgumentException - if the length is greater than maxPayloadLength() within an MTU.

See Also:

BufferClaim.commit(), BufferClaim.abort()

addDestination

public void addDestination(java.lang.String endpointChannel)

Add a destination manually to a multi-destination-cast Publication.

Parameters:

endpointChannel - for the destination to add

removeDestination

public void removeDestination(java.lang.String endpointChannel)

Remove a previously added destination manually from a multi-destination-cast Publication.

Parameters:

endpointChannel - for the destination to remove