com.softwareag.entirex.aci
Class Publication

java.lang.Object
  com.softwareag.entirex.aci.Publication

public class Publication
extends java.lang.Object

This class is the Java ACI for the Broker Publish & Subscribe ACI. The class holds a publication of the Broker, published or received. The publication can hold one or more messages. The messages are BrokerMessage objects. The publication is closed with commit and discarded with backout.

Since:

7.2.1

Field Summary

static java.lang.String	MSG_FIRST A publication status.
static java.lang.String	MSG_LAST A publication status.
static java.lang.String	MSG_MIDDLE A publication status.
static java.lang.String	MSG_ONLY A publication status.

Constructor Summary

Publication(Broker broker, java.lang.String topicName)
Create a publication with a given Broker and a topic name.

Method Summary

void	backout() Backs out this publication.
void	commit() Commits this publication.
java.lang.String	getPublicationId() Gets the publication ID.
java.lang.String	getPublicationStatus() Gets the status of the publication.
int	getReceiveLength() Gets the recieve length.
java.lang.String	getUserStatus() Gets the user status field of this publication.
java.lang.String	last() Gets the status of the last publication of this user.
void	publish(BrokerMessage message) Publishes a message within the topic.
java.lang.String	query() Gets the status of the publication given by the publication id.
BrokerMessage	receive() Receive a message within the topic with no wait time.
BrokerMessage	receive(java.lang.String wait) Receive a message within the topic with a wait time.
void	setPublicationId(java.lang.String publicationId) Sets the publication ID.
void	setReceiveLength(int receiveLength) Sets the recieve length.
void	setUserStatus(java.lang.String userStatus) Sets the user status field of this publication.
void	subscribe(boolean durable) Subscribes to the topic of this publication.
void	unsubscribe() Unsubscribes this subscriber from the topic.

Methods inherited from class java.lang.Object

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

Field Detail

MSG_ONLY

public static final java.lang.String MSG_ONLY

A publication status. This status is set if the message is the only message in a publication. No further calls of receive are allowed.

See Also:

Constant Field Values

MSG_LAST

public static final java.lang.String MSG_LAST

A publication status. This status is set if the message is the last message in a publication. No further calls of receive are allowed.

See Also:

Constant Field Values

MSG_FIRST

public static final java.lang.String MSG_FIRST

A publication status. This status is set if the message is the first message in a publication.

See Also:

Constant Field Values

MSG_MIDDLE

public static final java.lang.String MSG_MIDDLE

A publication status. This status is set if the message is not the first and not the last message in a publication, but 'in the middle' of a publication.

See Also:

Constant Field Values

Constructor Detail

Publication

public Publication(Broker broker,
                   java.lang.String topicName)

Create a publication with a given Broker and a topic name.

Parameters:

broker - the Broker. Must not equal null.

topicName - the name of the topic.

Throws:

java.lang.IllegalArgumentException - if the Broker is null.

Method Detail

publish

public void publish(BrokerMessage message)
             throws BrokerException

Publishes a message within the topic.

Parameters:

message - the BrokerMessage to publish.

Throws:

BrokerException - if the Broker returns an error or the publication ID is corrupt.

java.lang.IllegalArgumentException - if the message is null.

receive

public BrokerMessage receive()
                      throws BrokerException

Receive a message within the topic with no wait time. After receive check the status of the publication with getPublicationStatus. If the status is MSG_ONLY or MSG_LAST, commit or backout the publication and create a new Publication object before receiving the next message. The PublicationListen does this checking and always commits the publication.

Returns:

the received message.

Throws:

BrokerException - if the Broker returns an error or the publication ID is corrupt.

See Also:

getPublicationStatus(), PublicationListener, receive(java.lang.String)

receive

public BrokerMessage receive(java.lang.String wait)
                      throws BrokerException

Receive a message within the topic with a wait time. After receive check the status of the publication with getPublicationStatus. If the status is MSG_ONLY or MSG_LAST, commit or backout the publication and create a new Publication object before receiving the next message. The PublicationListen does this checking and always commits the publication.

Parameters:

wait - the timeout period, how long to wait for a message, measured in seconds/minutes/hours (depending on the trailing S/M/H character). When null or "NO" is specified, the operation is non-blocked. If no message is available, a BrokerException with errorclass=74 and errorcode=74 is thrown.

Returns:

the received message.

Throws:

BrokerException - if the Broker returns an error or the publication ID is corrupt or a wait time out occurs.

See Also:

getPublicationStatus(), PublicationListener, receive()

subscribe

public void subscribe(boolean durable)
               throws BrokerException

Subscribes to the topic of this publication. This method uses the user ID and the token of the Broker object as a subscriber name. Only the subscriber uses this method.

Parameters:

durable - if true, the subscription is stored in the Broker and it is valid until unsubscribe, even if this subscriber is not active.

Throws:

BrokerException - if the Broker returns an error.

unsubscribe

public void unsubscribe()
                 throws BrokerException

Unsubscribes this subscriber from the topic. The subscriber is identified by user ID and token in the logon call. Only the subscriber uses this method.

Throws:

BrokerException - if the Broker returns an error.

commit

public void commit()
            throws BrokerException

Commits this publication.

If a publisher commits a publication, this is visible for the subscribers and they can receive the publication. Once a publisher commits a publication, no more messages can be added.

If the subscriber commits a publication, it finished receiving messages of this publication. Afterwards, this subscriber cannot receive any unread message from this publication.

Throws:

BrokerException - if the Broker returns an error.

backout

public void backout()
             throws BrokerException

Backs out this publication.

If a publisher backs out a publication, all messages in this publication are deleted. Create a new Publication object before publishing new messages.

If a subscriber backs out a publication it can start to recieve the first and all following messages again.

Throws:

BrokerException - if the Broker returns an error.

last

public java.lang.String last()
                      throws BrokerException

Gets the status of the last publication of this user. Only used by the publisher. The search for the last publication considers only publications to topics where durable subscriptions are allowed.

Returns:

the status of the last publication.

Throws:

BrokerException - if the Broker returns an error.

getPublicationStatus

public java.lang.String getPublicationStatus()

Gets the status of the publication.

Returns:

the status of the publication.

See Also:

MSG_ONLY, MSG_FIRST, MSG_MIDDLE, MSG_LAST

query

public java.lang.String query()
                       throws BrokerException

Gets the status of the publication given by the publication id. Only used by the publisher.

Returns:

the status of the publication.

Throws:

BrokerException - if the Broker returns an error.

setUserStatus

public void setUserStatus(java.lang.String userStatus)
                   throws BrokerException

Sets the user status field of this publication. Publisher and subscriber can use this method.

Parameters:

userStatus - the user status.

Throws:

BrokerException - if the Broker returns an error.

getUserStatus

public java.lang.String getUserStatus()

Gets the user status field of this publication. Publisher and subscriber can use this method.

Returns:

the user status.

Since:

7.2.1.35

getReceiveLength

public int getReceiveLength()

Gets the recieve length. Only used by the subscriber.

Returns:

the receive length in bytes.

setReceiveLength

public void setReceiveLength(int receiveLength)

Sets the recieve length. The recieve length is the maximal length, a received message can have. Only used by the subscriber.

Parameters:

receiveLength - the receive length given in bytes.

getPublicationId

public java.lang.String getPublicationId()

Gets the publication ID. The publication ID can be stored by the application. With this ID the application can publish or receive further messages for this publication.

Returns:

the publication ID.

setPublicationId

public void setPublicationId(java.lang.String publicationId)

Sets the publication ID. Use this modifier to publish or receive messages for an existing publication. Set the ID before publish or receive.

Parameters:

publicationId - the publication ID.