org.apache.juddi.api.impl

Class UDDISubscriptionImpl

java.lang.Object

org.apache.juddi.api.impl.AuthenticatedService

org.apache.juddi.api.impl.UDDISubscriptionImpl

All Implemented Interfaces:

Remote, UDDISubscriptionPortType

public class UDDISubscriptionImpl
extends AuthenticatedService
implements UDDISubscriptionPortType

This is jUDDI's implementation of the UDDIv3 Subscription API

Field Summary

Fields

Modifier and Type	Field and Description
static String	CHUNK_TOKEN_PREFIX
static int	DEFAULT_CHUNKEXPIRATION_MINUTES
static int	DEFAULT_SUBSCRIPTIONEXPIRATION_DAYS

Fields inherited from class org.apache.juddi.api.impl.AuthenticatedService

AUTHTOKEN_ACTIVE, AUTHTOKEN_RETIRED, baseUrl, baseUrlSSL, ctx, df, UTF8

Constructor Summary

Constructors

Constructor and Description
UDDISubscriptionImpl()

Method Summary

Modifier and Type	Method and Description
void	deleteSubscription(DeleteSubscription body) Cancels an existing subscription.
protected void	doRenewal(Subscription existingSubscription, Subscription apiSubscription) Will perform the necessary logic for when a subscription is renewed (evidenced by a subscription with the same key in existence).
protected void	doSubscriptionExpirationDate(Subscription apiSubscription) Will add the expiration date to the provided subscription request.
protected List<?>	getSubscriptionMatches(SubscriptionFilter subscriptionFilter, javax.persistence.EntityManager em) Will take a snapshot of the keys that match the subscription filter return them.
SubscriptionResultsList	getSubscriptionResults(GetSubscriptionResults body) This API allows a subscriber to request that the information pertaining to an existing subscription be returned. This is useful, for example, to obtain historical data when a subscription is first set up or when a subscriber misses the notification normally provided by the registry. The results are returned synchronously as the response to this call. The get_subscriptionResults API can also be used as an alternative to notifications for obtaining subscription data.
SubscriptionResultsList	getSubscriptionResults(GetSubscriptionResults body, UddiEntityPublisher publisher)
List<Subscription>	getSubscriptions(String authInfo) Returns the complete list of existing subscriptions owned by the subscriber.
void	saveSubscription(String authInfo, Holder<List<Subscription>> subscription) The save_subscription API registers a request to monitor specific registry content and to have the node periodically notify the subscriber when changes are available.

Methods inherited from class org.apache.juddi.api.impl.AuthenticatedService

getEntityPublisher, getNode, getRequestorsIPAddress, setContext

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SUBSCRIPTIONEXPIRATION_DAYS

public static final int DEFAULT_SUBSCRIPTIONEXPIRATION_DAYS

See Also:

Constant Field Values

DEFAULT_CHUNKEXPIRATION_MINUTES

public static final int DEFAULT_CHUNKEXPIRATION_MINUTES

See Also:

Constant Field Values

CHUNK_TOKEN_PREFIX

public static final String CHUNK_TOKEN_PREFIX

See Also:

Constant Field Values

Constructor Detail

UDDISubscriptionImpl

public UDDISubscriptionImpl()

Method Detail

deleteSubscription

public void deleteSubscription(DeleteSubscription body)
                        throws DispositionReportFaultMessage

Description copied from interface: UDDISubscriptionPortType

Cancels an existing subscription.

Specified by:

deleteSubscription in interface UDDISubscriptionPortType

Parameters:

body -

· authInfo: This optional argument is an element that contains an authentication token. Registries that wish to restrict who can delete a subscription typically require authInfo for this call, though this is a matter of node policy.

· subscriptionKey: This required argument specifies, using anyURIs, the subscription or subscriptions to be deleted.

If no errors occur then an empty message is returned.

Throws:

DispositionReportFaultMessage

getSubscriptionResults

public SubscriptionResultsList getSubscriptionResults(GetSubscriptionResults body)
                                               throws DispositionReportFaultMessage

Description copied from interface: UDDISubscriptionPortType

This API allows a subscriber to request that the information pertaining to an existing subscription be returned. This is useful, for example, to obtain historical data when a subscription is first set up or when a subscriber misses the notification normally provided by the registry. The results are returned synchronously as the response to this call. The get_subscriptionResults API can also be used as an alternative to notifications for obtaining subscription data. If this is the preference, then the subscriber SHOULD not provide a bindingKey when saving the associated subscription. See Section 5.5.8 save_subscription. This API is not affected by the value of the notificationInterval in the subscription.

Specified by:

getSubscriptionResults in interface UDDISubscriptionPortType

Parameters:

body -

· authInfo: This optional argument is an element that contains an authentication token. Registries that wish to restrict who can retrieve subscription data typically require authInfo for this call, though this is a matter of node policy.

· chunkToken: This optional argument is used to retrieve subsequent groups of data when the first call to this API indicates more data is available. This occurs when a chunkToken is returned whose value is not "0" in the subscriptionResultsList structure described in the next section. To retrieve the next chunk of data, the value returned should be used as an argument to the next invocation of this API.

· coveragePeriod: This structure defines the time period over which the most recent changes in node data are compared with the subscription criteria in order to produce the result set. It provides start and end date/time information according to the format described in Section 5.5.4 Subscription Coverage Period. The "current" state of registry entries pertaining to the subscription referenced by the subscriptionKey provided are returned if they were last created, changed or deleted during the specified time period.

· subscriptionKey: This required argument of type anyURI identifies the subscription for which non-recurring synchronous results are being sought.

Returns:

returns org.uddi.sub_v3.SubscriptionResultsList

A subscriptionResultsList is returned whose content is determined by the coveragePeriod and the criteria in the subscription:

Attributes

Name	Use
someResultsUnavailable	optional

Subscription results MAY be chunked. See Section 5.5.5 Chunking of Returned Subscription Data, for more information on chunking of results. If results are chunked, then subsequent "chunks" can be retrieved using the chunkToken returned as an argument in a subsequent invocation of this API.

Note that the results returned in the subscriptionResultsList represent a snapshot of the current state of relevant entries in the registry. They are non-transactional in nature and prior states cannot be returned. Deleted entities and virtual deletes of entities, which have been changed in such a way that they no longer match the subscription criterion saved with the subscription, are returned only in the form of a keyBag structure, for which the deleted element is set to "true". A UDDI node MAY inform a subscriber about the real or virtual deletion of an entity multiple times.

The someResultsUnavailable attribute is set to "true" whenever the node has found it necessary to flush subscription results information pertaining to entity deletions (either actual or virtual) which pertain to this subscription, which have not yet been reported through prior calls to this API, or through use of the notify_subscriptionListener API described below. The period of time which a node retains information on deletions for a given subscription is a matter of node policy.

The API used in the subscription filter determines the sort order for returned entities. By default, they will be sorted according to the behavior specified in the "returns" section of that API.

Throws:

DispositionReportFaultMessage

getSubscriptionResults

public SubscriptionResultsList getSubscriptionResults(GetSubscriptionResults body,
                                                      UddiEntityPublisher publisher)
                                               throws DispositionReportFaultMessage

Throws:

DispositionReportFaultMessage

getSubscriptions

public List<Subscription> getSubscriptions(String authInfo)
                                    throws DispositionReportFaultMessage

Description copied from interface: UDDISubscriptionPortType

Returns the complete list of existing subscriptions owned by the subscriber.

Specified by:

getSubscriptions in interface UDDISubscriptionPortType

Parameters:

authInfo - authInfo: This optional argument is an element that contains an authentication token. Registries that wish to restrict who can obtain information on subscriptions typically require authInfo for this call, though this is a matter of node policy.

Returns:

returns java.util.List This API call returns information on all of the subscriptions owned by the subscriber, together with the expiration date for each. The subscriptions structure returned contains zero or more subscription structures, each pertaining to a subscription. Only subscriptions created by the invoking subscriber are returned. See Section 5.5.8.1, [save_subscription] Syntax, for details on these structures.

Throws:

DispositionReportFaultMessage

saveSubscription

public void saveSubscription(String authInfo,
                             Holder<List<Subscription>> subscription)
                      throws DispositionReportFaultMessage

Description copied from interface: UDDISubscriptionPortType

The save_subscription API registers a request to monitor specific registry content and to have the node periodically notify the subscriber when changes are available. Notifications are not returned synchronously with results for this API. Only data that matches the requested subscription criteria and which changes after the point in time that the subscription request is accepted is returned to the subscriber via a notification. This API returns a duration for which this particular subscription is valid. Depending upon the policy of the Node, subscriptions need to be renewed before the expiration date in order to insure that they remain active. Subscriptions can also be redefined or renewed using this API. The subscriptionKey pertaining to the subscription to be renewed must be supplied in the save_subscription invocation in order to accomplish this. This allows both renewal and changes to the subscription. Invoking save_subscription automatically resets the expiration period for the subscription in question to a value based upon the node’s policy.

The syntax of the subscription structure is:

Attributes

Name	Use
brief	optional

The syntax of the subscriptionFilter structure is:

Specified by:

saveSubscription in interface UDDISubscriptionPortType

Parameters:

authInfo - authInfo: This optional argument is an element that contains an authentication token. Registries that wish to restrict who can save a subscription typically require authInfo for this call, though this is a matter of node policy.

return

Upon successful completion this API returns a subscriptions structure. Included in the subscription structure(s) it MUST contain is a subscriptionKey (of type anyURI) that is used by the subscriber to manage the subscription. This key is required in order to delete (unsubscribe), modify or renew the subscription. If a subscriber has multiple subscriptions, the subscriptionKey can be used to distinguish between different subscriptions. The subscriptionKey is also part of the data contained in the notifications returned to subscription listeners.

The subscription structure(s) returned from this API, MUST each contain an expiresAfter value, which has been assigned by the node. Nodes SHOULD attempt to honor the value(s) provided with the save_subscription request, but MAY modify them based on node policy. Depending upon the node’s policy, the node MAY delete a subscription after it has expired.

The value of the notificationInterval included in the subscription structure(s) returned MAY be adjusted by the node to the value closest to that requested which is supported by its policies. Depending upon the Registry’s workload a node MAY skip a notification cycle. If a cycle is skipped, the next notification sent SHOULD include information based on registry activity, which has occurred since the last notification was issued.

subscription -

· bindingKey: This optional argument of type anyURI specifies the bindingTemplate which the node is to use to deliver notifications to subscription listeners. It is only required when asynchronous notifications are used. This bindingTemplate MUST define either a Web service that implements notify_subscriptionListener (see below), or an email address to receive the notifications. If a notify_subscriptionListener Web service is identified, the node invokes it to deliver notifications. If an email address is identified, the node delivers notifications via email to the address supplied. When notifications are delivered via email, the body of the email contains the body of the SOAP message, which would have been sent to the notify_subscriptionListener service if that option had been chosen.. The publisher making the subscription request MUST own the bindingTemplate. If this argument is not supplied, no notifications are sent, although subscribers may still use the get_subscriptionResults API to obtain subscription results. See Section 5.5.11 get_subscriptionResults for details. If email delivery to the specified address fails, nodes MAY attempt re-delivery, but are not obligated to do so. Depending upon node policy, excessive delivery failures MAY result in cancellation of the corresponding subscription.

· brief: This optional argument controls the level of detail returned to a subscription listener. The default is "false" when omitted. When set to "true," it indicates that the subscription results are to be returned to the subscriber in the form of a keyBag, listing all of the entities that matched the subscriptionFilter. Refer to Section 5.5.6 Use of keyBag in Subscription, for additional information. This option has no effect on the assertionStatusReport structure, which is returned as part of a notification when the subscriptionFilter specifies the get_assertionStatusReport filter criteria. See the explanation of subscriptionFilter below.

· expiresAfter: This optional argument allows subscribers to specify the period of time for which they would like the subscription to exist. It is of the XML Schema type xsd:dateTime. Specifying a value for this argument is no guarantee that the node will accept it without change. Information on the format of expiresAfter can be found in Section 5.5.1.1 Specifying Durations.

· maxEntities: This optional integer specifies the maximum number of entities in a notification returned to a subscription listener. If not specified, the number of entities sent is not limited, unless by node policy.

· subscriptionFilter: This argument specifies the filtering criteria which limits the scope of a subscription to a subset of registry records. It is required except when renewing an existing subscription. The get_xx and find_xx APIs are all valid choices for use as a subscriptionFilter. Only one of these can be chosen for each subscription. Notifications, based on the subscriptionFilter, are sent to the subscriber if and only if there are changes at the node, which match this criterion during a notification period. A subscriptionFilter MUST contain exactly one of the allowed inquiry elements. The authInfo argument of the specified get_xx or find_xx API call is not required here and is ignored if specified. All of the other arguments supported with each of these inquiry APIs are valid for use here.

Specifying find_relatedBusinesses is useful for tracking when reciprocal relationships are formed or dissolved. Specifying get_assertionStatusReport can be used in tracking when reciprocal relationships (which pertain to a business owned by the subscriber) are formed, dissolved, or requested by the owners of some other business.

For a get_assertionStatusReport based subscription, there is a specific status value, status:both_incomplete, defined in the XML schema. When appearing in an assertionStatusItem of a subscriptionResultsList, status:both_incomplete indicates that the publisher assertion embedded in the assertionStatusItem has been deleted from both ends.

Note that the above handling of deleted publisher assertions is different from the case when a business entity, business service, binding template, or tModel is removed. In the latter case, the key to the entity in question is simply put inside a keyBag. A publisher assertion, on the other hand, has no key and therefore the keyBag idea is not applicable.

· subscriptionKey: This optional argument of type anyURI identifies the subscription. To renew or change an existing subscription, a valid subscriptionKey MUST be provided. When establishing a new subscription, the subscriptionKey MAY also be either omitted or specified as an empty string in which case the node MUST assign a unique key. If subscriptionKey is specified for a new subscription, the key MUST conform to the registry’s policy on publisher-assigned keys.

· notificationInterval: This optional argument is only required when asynchronous notifications are used. It is of type xsd:duration and specifies how often change notifications are to be provided to a subscriber. If the notificationInterval specified is not acceptable due to node policy, then the node adjusts the value to match the next longer time period that is supported. The adjusted value is provided with the returns from this API. Also see Section 5.5.1.1 Specifying Durations.

Throws:

DispositionReportFaultMessage

doRenewal

protected void doRenewal(Subscription existingSubscription,
                         Subscription apiSubscription)
                  throws DispositionReportFaultMessage

Will perform the necessary logic for when a subscription is renewed (evidenced by a subscription with the same key in existence). In general, the appropriate data is copied from the stored subscription to the renewal subscription request.

Parameters:

existingSubscription - - existing stored subscription

apiSubscription - - renewal subscription request

Throws:

DispositionReportFaultMessage

doSubscriptionExpirationDate

protected void doSubscriptionExpirationDate(Subscription apiSubscription)
                                     throws DispositionReportFaultMessage

Will add the expiration date to the provided subscription request. Date is earlier of user provided date and the system default

Parameters:

apiSubscription -

Throws:

DispositionReportFaultMessage

getSubscriptionMatches

protected List<?> getSubscriptionMatches(SubscriptionFilter subscriptionFilter,
                                         javax.persistence.EntityManager em)
                                  throws DispositionReportFaultMessage

Will take a snapshot of the keys that match the subscription filter return them. Currently, keys are only returned for the find_* filters. It seems redundant to return the keys in the get_*Detail filters.

Parameters:

subscriptionFilter -

em -

Returns:

a list of subscription matches

Throws:

DispositionReportFaultMessage