This portType defines all of the UDDI publication operations.
This class was generated by the JAX-WS RI. JAX-WS RI 2.1.5-b03- Generated
source version: 2.1
Publication API Set
The API calls in this section are used to publish and
update information contained in a UDDI registry. According to the
policy of the UDDI registry, a publisher selects a UDDI node where it will
publish the information.
API calls in this section MUST all be implemented as
synchronous and "atomic" from the point of view of the caller. That is, each
call MUST either succeed completely or fail completely. Partial results MUST
NOT be returned.
When a publisher does not provide keys for new
entities, the UDDI node will assign keys in accordance with registry policy.
Node-assigned keys MUST use keys that conform to the grammar in Section 4.4 About uddiKeys.
The registry keying policy MAY allow an entity’s key
to be proposed by the publisher. If the publisher does not propose a key for
an entity, the registry MUST assign one.
Since entity keys MUST be unique in a registry without
regard to the type of entity and since registries MUST define to impose
policies concerning which publishers may publish which keys,
publisher-assigned keys are subject to rules that UDDI registries enforce.
Behavior that ensures uniqueness across entity types (businessEntity,
businessService, bindingTemplate, tModel and subscription) is REQUIRED for
all registries. In this section we discuss the behavior of registries that
use the recommended "uddi:" key structure. This behavior provides uniqueness
and promotes interoperability among registries, while allowing various
registry-specific policies to be built. Practical guidance for the use of
this facility may be found in Section 9.4.2
General Keying Policy and Section 9.4.3
Policy Abstractions for the UDDI keying scheme.
To ensure that publisher-generated keys do not
conflict with one another, registries assign the authority to generate keys
to publishers in the following manner:
1. The conceptual space
of uddiKeys is divided into non-overlapping, hierarchically arranged
partitions, each of which can be associated with a publisher.
2. Only the publisher
associated with a particular partition is given the authority to assign keys
within the partition.
3. The publisher with
authority for a given partition may designate any publisher it chooses for
any partition directly below the partition it manages, provided it has not
already designated a publisher to that partition.
4. The publisher with
authority for a partition may transfer its authority to another
publisher.
5. Initially, the
registry itself has authority for the root partition of the hierarchy.
The specific mechanisms that enforce these rules are
explained below.
Each node of a registry is a generator of keys.
This is required to enable the node to generate keys not provided by
publishers. In addition, the policies of a registry MAY allow individual
publishers to obtain the authority to be generators of keys for specific
partitions within the space of uddiKeys. Publishers obtain this authority by
owning a particular tModel called a key generator tModel. The key
generator tModel contains a key generator key, and it specifies the partition
for which the publisher may assign keys.
The subset of
derivedKeys called key generator keys consists of all the keys of the
form:
keyGeneratorKey
=
uddiKey ":keygenerator"
As described in Section 4.4.1, a derivedKey is one
that is formed from another key by appending a non-empty, colon-prefixed
string to another uddiKey. A derivedKey is said to be "based on" this
uddiKey. With this in mind, the complete partition of a given keyGeneratorKey
is the set of keys consisting of:
1. The set of
derivedKeys based on the same uddiKey that the keyGeneratorKey is based
upon.
2. The set of
keyGeneratorKeys based on a key that is in the partition.
3. The domainKey, if
the keyGeneratorKey is based upon that domainKey.
Note that the partition's keyGeneratorKey itself is
exluded from the partition.
A rootKeyGeneratorKey is a keyGeneratorKey that is not
based on a derivedKey. That is:
rootKeyGeneratorKey
= (uuidKey /
domainKey) ":keygenerator"
5.2.2.1.1 Examples
Based on the rules above, it is possible to construct
the keyGeneratorKey for any key by manipulating the string representation of
the key. To illustrate, suppose the key is x, then the following pseudo-code
will determine the keyGeneratoryKey:
If x is a keyGeneratorKey, and y is that key minus the
":keygenerator" suffix,
then if y is a domainKey
then x is a top-level keyGenerator, and
has no keyGeneratorKey (1.a)
else y is a derivedKey, based on z,
and x’s
keyGeneratorKey is z:keyGenerator (1.b)
else
If x is a domainKey
then x’s keyGeneratorkey is
x:keyGenerator (2)
else x is based on a key y, and x’s keyGenerator is
y:keyGenerator (3)
Using this pseudo-code illustration, the following
table provides examples of legal URI’s and their associated key generators
for each of the four cases noted:
Key | keyGeneratorKey
| Case in pseudo-code |
uddi:tempuri.com | uddi:tempuri.com:keygenerator | 2 |
uddi:tempuri.com:keygenerator | <none> | 1.a |
uddi:tempuri.com:xxx:keygenerator | uddi:tempuri.com:keygenerator | 1.b |
uddi:tempuri.com:xxx | uddi:tempuri.com:keygenerator | 3 |
uddi:tempuri.com:xxx:yyy | uddi:tempuri.com:xxx:keygenerator | 3 |
The following keys do NOT belong to the partition of
the key generator key "uddi:tempuri.com:keygenerator".
"uddi:tempuri.com:keygenerator" | The keyGeneratorKey does not belong to the partition it
designates. |
"uddi:tempuri.com:xxx:yyy" | This key belongs to the partition of the keyGeneratorKey
"uddi:tempuri.com:xxx:keygenerator", not this one. |
"uddi:tempuri.com:keygenerator:zzz" | This key does not belong in any partition – it is an
invalid key. |
To successfully publish a new entity with a proposed
key, the publisher needs to own the key generator tModel for the partition in
which the key lies. Typically, a publisher gets ownership by publishing the
tModel in question, but publishers can also get ownership in other ways, for
example by having another publisher transfer ownership.
Once a publisher owns a key generator tModel that
publisher MAY publish new entities[20]
and assign them keys within the key generator tModel’s partition. New keys
can only be generated from keyGenerator tModels that are not hidden.
Publishers are responsible for managing the uniqueness of the keys in the
partition they own. If a publisher fails to do so, and generates an already
used key, a publish operation could inadvertently replace an entity
previously published by that publisher.
If a publisher owns key generator tModels with the
same key in multiple registries – for example one in the publisher’s private
test registry and one in the UDDI Business Registry – that publisher MAY
publish the entities with identical keys in those registries. This enables
many interesting capabilities. For example, publishers may choose to develop
their UDDI entities by publishing them into test registries and then, at
appropriate times, "promote" them to the UDDI Business Registry.
To ensure that publisher-assigned keys work correctly
all UDDI implementations behave as follows.
5.2.2.3.1 "New" and "existing"
entities defined
During a publish operation, the entity or entities
being published are either "new" or "existing". An existing entity is one
that has a key that matches the key of an entity already in the registry. A
new entity is one that does not. If a new entity has a key, this key is the
key proposed for that entity by its publisher.
5.2.2.3.2 Behavior with respect
to entities for which no key is proposed.
A UDDI node MUST generate and assign a key to each
entity for which the publisher proposes no key. It may generate uuidKeys for
use as the keys of new entities for which no key is proposed or it may
generate keys in the partition of a key generator tModel it owns.
A registry whose nodes assign uddiKeys to new entities
is called a root registry. The UDDI Business Registry is a root registry. A
registry whose nodes gain ownership of their key generator tModels by
publishing them in the UDDI Business Registry are affiliates of the UDDI
Business Registry. See Section 1.5.5
Affiliations of Registries.
5.2.2.3.3 Behavior with respect
to uuidKeys
A UDDI node SHOULD accept a uuidKey as the key for a
new entity during a publish operation if the publisher is a trusted publisher
of such keys, according to the policies of the registry. UDDI nodes MUST NOT
allow other publishers to generate uuidKeys.
5.2.2.3.4 Behavior with respect
to key generator keys
A UDDI node MUST NOT publish any non-tModel entity
whose proposed key is a key generator key. A tModel whose proposed key
is a key generator key MUST include a category bag with a keyed reference
with the tModelKey set to "uddi:uddi.org:categorization:types" and the
keyValue set to "keyGenerator".
5.2.2.3.5 Behavior with respect
to root key generator keys
During a publish operation a UDDI node SHOULD accept a
root key generator key as the key for a new tModel if it is proposed by a
publisher authorized to publish the key, according to the policies of the
registry. The policy MUST prevent more than one publisher from publishing
tModels with the same root key generator key.
An appropriate policy for root and for affiliated
registries is given in Chapter 9
Policy.
5.2.2.3.6 Behavior with respect
to other proposed keys
A UDDI node SHOULD accept keys proposed for new
entities during publishing operations if they meet both of the following
criteria.
·
The proposed key lies in
the partition of the key of an existing key generator tModel and the key
generator tModel is not hidden.
·
The same publisher who is proposing the new key owns the key
generator tModel referred to in the previous bullet. [21]
5.2.2.4 Affiliations of
registries
A set of registries may cooperate in managing a single
multi-registry key space by designating one of the registries in the group to
be the "root registry" and assigning it to be the authority for the root
partition. Other registries in the set are said to be affiliate
registries. See Section 1.5.5
Affiliations of Registries for more information
The UDDI Business Registry is a root registry. Its
policies and procedures are designed to make it simple for any UDDI registry
to be affiliated with it.
Designating new authorities is done by publishing key
generator tModels in the root registry, in one or more of the registries
affiliated with the root registry or both. The owner of a key generator
tModel is the naming authority for the partition the tModel represents.
Several of the APIs defined in this section allow
publishers to save category and identifier information in support of searches
that use category and identifier system references. The save_business,
save_service, save_binding and save_tModel APIs allow designation of these
value set references. Categorization is specified using the element
named categoryBag, which contains namespace-qualified references to
categories and descriptions. categoryBags can also contain groups of
these references to categories and descriptions. Identifiers are
specified using the identifierBag element, which contains namespace-qualified
references to identifiers and descriptions.
Similarly, the add_publisherAssertions and
set_publisherAssertions APIs allow publisherAssertion elements to be
saved. These publisherAssertion elements contain a characterization of
the relationship being established using a keyedReference element that refers
to a relationship type system.
Identifier, category and relationship type systems
taken together are referred to as "value sets." UDDI allows value sets
to be checked or unchecked. References to checked value sets that are
registered in UDDI can be checked internally by the UDDI nodes where
publishing takes place, or externally by a provider of a validation Web
service. The UDDI node can also choose to not support some or all
checked value sets.
When a UDDI node encounters a reference to a checked
value set in a keyedReference it will either ensure the reference is
validated or fail the save. Such references to supported checked value
sets are verified for validity according to the validation algorithm defined
for the value set and described by its tModel. When all checks succeed,
the save is permitted. An E_unvalidatable error indicates the checked
value set is supported but its validation algorithm is not available.
An E_unsupported indicates the checked value set is not supported by the
node. E_invalidValue or E_valueNotAllowed indicate one or more
references failed validation. When the checked value set is not
supported, the value set’s validation algorithm is unavailable, or any of the
references fail validation, the save operation MUST fail.
When the UDDI node supports a checked value set it may
check the references itself, or consult a validation Web service. For
cached checked value sets, the UDDI node verifies that referenced keyValues
are in the set of valid values for the value set. The selection of an
algorithm for verifying a checked value set is a matter of registry policy as
detailed in Chapter 9 Policy.
A category group system is portrayed by a
keyedRefererenceGroup element. Each keyedReferenceGroup has a tModelKey
that references the category group system, and a set of contained
keyedReference elements that make up the actual group of categories.
Similar to references to checked value sets, validation is carried out for a
keyedReferenceGroup if the referenced category group system is checked.
Such validation entails verification that the keyedReferenceGroup is valid
according to the validation algorithm described by the tModel for the
category group system. Validation for a keyedReferenceGroup that
references a cached checked category group system involves verification that
the tModels referenced by the contained keyedReference elements are valid for
the category group system. The set of valid values for such a cacheable
checked category group system is defined by the tModelKeys for the set of
tModels that can participate in the group.
No validation is performed on references to unchecked
value sets
5.2.4 Special considerations for the xml:lang
attribute
During save_xx API calls, the name, description,
address, and personName UDDI elements MAY be adorned with the xml:lang
attribute to indicate the language in which their content is expressed. (See
Chapter 3 UDDI Registry Data
Structures.) When an optional xml:lang attribute is omitted from an
element, no xml:lang attribute will be saved for that element.
Name elements in UDDI core data structures are
frequently the main targets for sorts during UDDI inquiries. When a
UDDI data structure has multiple names, sorting occurs on the first
name. Care should be taken to list the primary name first when the
entity is saved to ensure the proper placement of the entity in a sorted
result set.
Values which can be passed in the language supplied in
a save_xx API call MUST obey the recommended rules and syntax governing the
xml:lang data type as defined in Section 3.3.2.3
name.
The publishing API calls are:
·
add_publisherAssertions: Used to add
relationship assertions to the existing set of assertions. See Appendix
A Relationships and Publisher Assertions.
·
delete_binding: Used to remove an
existing bindingTemplate from the registry.
·
delete_business: Used to delete existing
businessEntity information from the registry.
·
delete_publisherAssertions:
Used to delete specific publisher assertions from the assertion collection
controlled by a particular publisher. Deleting assertions from the
assertion collection affects the visibility of business relationships.
Deleting an assertion causes any relationships based on that assertion to
become incomplete.
·
delete_service: Used to delete an
existing businessService from the registry.
·
delete_tModel: Used to hide existing
information about a tModel. Any tModel hidden in this way is still
usable for reference purposes and accessible via the get_tModelDetail API,
but is hidden from find_tModel result sets. There is no specified way
to delete a tModel.
·
get_assertionStatusReport: Used to get a
status report containing publisher assertions and status information.
This report is useful to help an administrator manage publisher assertions.
Returns an assertionStatusReport that includes the status of all assertions
made involving any businessEntity controlled by the requesting publisher.
·
get_publisherAssertions: Used to get a
list of publisher assertions that are controlled by an individual
publisher. Returns a publisherAssertions structure containing all
publisher assertions associated with a specific publisher.
·
get_registeredInfo: Used to request an
abbreviated list of businesses and tModels currently managed by a given
publisher.
·
save_binding: Used to register new
bindingTemplate information or to update existing bindingTemplate
information. Use this to control information about technical
capabilities exposed by a registered business.
·
save_business: Used to register new
businessEntity information or update existing businessEntity
information. Use this to control the full set of information about the
entire business, including its businessService and bindingTemplate
structures. This API has the broadest effect of all of the save_xx
APIs.
·
save_service: Used to register or
update complete information about a businessService.
·
save_tModel: Used to register or
update information about a tModel.
·
set_publisherAssertions: Used to save
the complete set of publisher assertions for an individual publisher.
Replaces any existing assertions, and causes any old assertions that are not
reasserted to be removed from the registry.