com.inprise.vbroker.PortableServerExt
Interface PSAOperations

All Superinterfaces:

POAOperations

All Known Subinterfaces:

PSA

public interface PSAOperations
extends POAOperations

The Publisher/Subscriber Adapter interface. This is a VisiBroker extension to POA interface. PSA is mainly a programming model and a software component working on top of OMG standardized Notification Service. Therefore, PSA can be used along with third party OMG Notification Service implementations and is also interchangeable with applications which are directly built with low-level OMG Notification Service interfaces.

One of the basic functions of the PSA is to hide the details pertaining to channel connections. Typically, when designing a CORBA publish/subscribe application, the main goal is to make the application consumer object receive events from a given channel. The channel is usually specified by its channel reference or consumer admin reference. The consumer object is usually specified by its POA and object id. By using OMG Notification Service directly, the application requires multiple steps in connecting the consumer object to the channel. However, by using PSA, the application only needs a single operation to complete this connection.

Method Summary

byte[]	publish(SubjectScheme the_subject_scheme, Object the_subject, byte[] the_pullable_publisher_id, NameValuePair[] the_properties) Attaches a supplier object or source to a notification/event channel that provides (either push or pull) event messages.
int	pull_and_dispatch(byte[] the_subscribe_desc, int max_count, boolean block_pulling, boolean async_dispatch) Pulls (typed) event and dispatch it to a registered observer.
int	pull_and_visit(byte[] the_subscribe_desc, int max_count, boolean block_pulling, Servant the_visitor) Pulls (typed) event and accept a given visitor to 'visit' the event.
void	resume(byte[] the_desc) Resumes subject to push into the registered observer or resumes subject to pull from the registered provider.
byte[]	subscribe(SubjectScheme the_subject_scheme, Object the_subject, byte[] the_observer_id, NameValuePair[] the_properties) Allows a consumer object to attach to a notification/ event source for receiving (either push or pull) event messages.
void	suspend(byte[] the_desc) Suspends subject to push into the registered observer or suspends subject to pull from the registered provider
Object	the_proxy_addr(byte[] the_desc)
Object	the_subject_addr(byte[] the_desc) Returns the pull address for untyped/structured/sequence pull consumers.
void	unpublish(byte[] the_publish_desc) Disconnects the supplier from a connected channel and cleans up any local resource.
void	unsubscribe(byte[] the_subscribe_desc) Disconnects the consumer from a connected channel and cleans up any local resource, if necessary (for multicast case, it remove the subject key to observer id mapping).

Methods inherited from interface com.inprise.vbroker.PortableServerExt.POAOperations

the_policies

Methods inherited from interface org.omg.PortableServer.POAOperations

activate_object_with_id, activate_object, create_id_assignment_policy, create_id_uniqueness_policy, create_implicit_activation_policy, create_lifespan_policy, create_POA, create_reference_with_id, create_reference, create_request_processing_policy, create_servant_retention_policy, create_thread_policy, deactivate_object, destroy, find_POA, get_servant_manager, get_servant, id_to_reference, id_to_servant, id, reference_to_id, reference_to_servant, servant_to_id, servant_to_reference, set_servant_manager, set_servant, the_activator, the_activator, the_children, the_name, the_parent, the_POAManager, the_POAManagerFactory

Method Detail

the_proxy_addr

Object the_proxy_addr(byte[] the_desc)
                      throws InvalidSubjectScheme

Throws:

InvalidSubjectScheme

the_subject_addr

Object the_subject_addr(byte[] the_desc)
                        throws InvalidSubjectScheme

Returns the pull address for untyped/structured/sequence pull consumers.

Parameters:

the_subscribe_desc - Subscribe descriptor returned by the subscribe operation.

Throws:

InvalidSubjectScheme

pull_and_visit

int pull_and_visit(byte[] the_subscribe_desc,
                   int max_count,
                   boolean block_pulling,
                   Servant the_visitor)
                   throws InvalidSubscribeDesc,
                          InvalidSubjectScheme,
                          ChannelException

Pulls (typed) event and accept a given visitor to 'visit' the event.

Throws:

InvalidSubscribeDesc

InvalidSubjectScheme

ChannelException

pull_and_dispatch

int pull_and_dispatch(byte[] the_subscribe_desc,
                      int max_count,
                      boolean block_pulling,
                      boolean async_dispatch)
                      throws InvalidSubscribeDesc,
                             InvalidSubjectScheme,
                             ChannelException

Pulls (typed) event and dispatch it to a registered observer.

Throws:

InvalidSubscribeDesc

InvalidSubjectScheme

ChannelException

resume

void resume(byte[] the_desc)
            throws ChannelException

Resumes subject to push into the registered observer or resumes subject to pull from the registered provider.

Parameters:

the_desc - Subscribe/Publish descriptor returned by the subscribe/publish operations.

Throws:

ChannelException

suspend

void suspend(byte[] the_desc)
             throws ChannelException

Suspends subject to push into the registered observer or suspends subject to pull from the registered provider

Parameters:

the_desc - Subscribe/Publish descriptor returned by the subscribe/publish operations.

Throws:

ChannelException

unpublish

void unpublish(byte[] the_publish_desc)
               throws InvalidPublishDesc,
                      ChannelException

Disconnects the supplier from a connected channel and cleans up any local resource. If the supplier is connected to an untyped and typed channel, the PSA invokes disconnect_push/pull_consumer() to the proxy. If it is connected to structured or sequence channel, the PSA respectively invokes disconnect_structured_push/pull_consumer() or disconnect_sequence_push/ pull_consumer().

Parameters:

the_publish_desc - Publish descriptor returned by the publish operation.

Throws:

InvalidPublishDesc

ChannelException

unsubscribe

void unsubscribe(byte[] the_subscribe_desc)
                 throws InvalidSubscribeDesc,
                        ChannelException

Disconnects the consumer from a connected channel and cleans up any local resource, if necessary (for multicast case, it remove the subject key to observer id mapping). If the consumer is connected to an untyped and typed channel, the PSA invokes disconnect_push/pull_supplier() to the proxy.

If the consumer is connected to structured or sequence channel, the PSA, respectively, invokes disconnect_structured_push/pull_supplier() or disconnect_sequence_push/pull_supplier().

Parameters:

the_subscribe_desc - Subscribe descriptor returned by the subscribe operation.

Throws:

InvalidSubscribeDesc

ChannelException

publish

byte[] publish(SubjectScheme the_subject_scheme,
               Object the_subject,
               byte[] the_pullable_publisher_id,
               NameValuePair[] the_properties)
               throws InvalidSubjectScheme,
                      InvalidProperties,
                      ChannelException

Attaches a supplier object or source to a notification/event channel that provides (either push or pull) event messages.

When the publish operation is used on top of the COS Notification, it performs all operation of getting supplier admin, obtaining proxy consumers, and connecting to them. Additionally, when the publish operation used with a typed subject, PSA also calls get_typed_consumer() on the proxy consumers to get the <I> reference.

Parameters:

the_subject_scheme - Specifies what are the subject reference's address scheme, interface scheme, interface repository id (for typed channel only) and delivery scheme.

the_subject - Reference of the subject. The subject reference's interpretation is specified by the SubjectScheme as the first parameter to this method.

the_pullable_publisher_id - specifies which supplier object should be used by PSA to pull events for publishing.

the_properties - Sets QoS policy on a connected proxy within a PSA.

Returns:

After a successful publish() operation, a publish descriptor is returned. It contains information/mapping to implement other publish() operations, such as unpublish(), suspend(), and resume(). This descriptor can be saved into a persistent repository and reloaded into the same supplier process session or a restart of a new supplier session. However, the format of this descriptor is internal to the ORB that creates it. Therefore, like the object key, a subscribe descriptor should only be used by the same ORB.

Throws:

InvalidSubjectScheme

InvalidProperties

ChannelException

subscribe

byte[] subscribe(SubjectScheme the_subject_scheme,
                 Object the_subject,
                 byte[] the_observer_id,
                 NameValuePair[] the_properties)
                 throws InvalidSubjectScheme,
                        InvalidProperties,
                        ChannelException

Allows a consumer object to attach to a notification/ event source for receiving (either push or pull) event messages.

When PSA is used on top of COS Notification, this operation performs all low-level operations of getting consumer admin, obtaining proxy suppliers and making the connection. For subscribing to a typed subject, the PSA also creates and manages the handler proxy object internally to support the get_typed_consumer() operation and only require the application to supply the observer servant implementation that support the application specified typed <I> interface.

Parameters:

the_subject_scheme - Specifies what is the subject reference's address scheme, interface scheme, interface repository id (for typed channel only), and delivery scheme.

the_subject - Reference of the subject. The subject reference's interpretation is specified by the SubjectScheme as the first parameter to this method.

the_observer_id - Specifies which consumer object, a received event, can be dispatched to.

the_properties - Sets QoS policy on a connected proxy within a PSA.

Returns:

After a successful subscribe() operation, a subscribe descriptor is returned which encapsulates all information and mapping to make other operations on the subscription, such as unsubscribe(), suspend(), resume(). Also, this descriptor can be saved into a persistent repository and can be later loaded into the same consumer process session or a new restarted consumer process session. However, the format of this descriptor is internal to the given ORB which created it. Therefore, like the object key, a subscribe descriptor must be used by the same ORB that created it.

Throws:

InvalidSubjectScheme

InvalidProperties

ChannelException