org.omg.CosTrading
Interface LookupOperations

All Superinterfaces:
ImportAttributesOperations, SupportAttributesOperations, TraderComponentsOperations
All Known Subinterfaces:
Lookup
All Known Implementing Classes:
_LookupStub, Lookup, LookupPOA, LookupPOATie

public interface LookupOperations
extends TraderComponentsOperations, SupportAttributesOperations, ImportAttributesOperations

The Lookup interfaces is resolved by "TradingService". It provides access to all trader attributes and to the query operation.


Method Summary
 void query(java.lang.String type, java.lang.String constr, java.lang.String pref, Policy[] policies, SpecifiedProps desired_props, int how_many, OfferSeqHolder offers, OfferIteratorHolder offer_itr, PolicyNameSeqHolder limits_applied)
          The query operation is the means by which an object can obtain references to other objects that provide services meeting its requirements.
 
Methods inherited from interface org.omg.CosTrading.TraderComponentsOperations
admin_if, link_if, lookup_if, proxy_if, register_if
 
Methods inherited from interface org.omg.CosTrading.SupportAttributesOperations
supports_dynamic_properties, supports_modifiable_properties, supports_proxy_offers, type_repos
 
Methods inherited from interface org.omg.CosTrading.ImportAttributesOperations
def_follow_policy, def_hop_count, def_match_card, def_return_card, def_search_card, max_follow_policy, max_hop_count, max_list, max_match_card, max_return_card, max_search_card
 

Method Detail

query

void query(java.lang.String type,
           java.lang.String constr,
           java.lang.String pref,
           Policy[] policies,
           SpecifiedProps desired_props,
           int how_many,
           OfferSeqHolder offers,
           OfferIteratorHolder offer_itr,
           PolicyNameSeqHolder limits_applied)
           throws IllegalServiceType,
                  UnknownServiceType,
                  IllegalConstraint,
                  IllegalPreference,
                  IllegalPolicyName,
                  PolicyTypeMismatch,
                  InvalidPolicyValue,
                  IllegalPropertyName,
                  DuplicatePropertyName,
                  DuplicatePolicyName
The query operation is the means by which an object can obtain references to other objects that provide services meeting its requirements. The type parameter conveys the required service type. It is key to the central purpose of trading: to perform an introduction for future type safe interactions between importer and exporter. By stating a service type, the importer implies the desired interface type and a domain of discourse for talking about properties of the service. If the string representation of the type does not obey the rules for service type identifiers, then an IllegalServiceType exception is raised. If the type is correct syntactically but is not recognized as a service type within the trading scope, then an UnknownServiceType exception is raised. The trader may return a service offer of a subtype of the type requested. Sub-typing of service types is discussed in Service Types on page 16-4. A service subtype can be described by the properties of its supertypes. This ensures that a well-formed query for the type is also a well-formed query with respect to any subtypes. However, if the importer specifies the policy of exact_type_match = TRUE, then only offers with the exact (no subtype) service type requested are returned. The constraint constr is the means by which the importer states those requirements of a service that are not captured in the signature of the interface. These requirements deal with the computational behavior of the desired service, non-functional aspects, and non-computational aspects (such as the organization owning the objects that provide the service). An importer is always guaranteed that any returned offer satisfies the matching constraint at the time of import. If the constr does not obey the syntax rules for a legal constraint expression, then an IllegalConstraint exception is raised. The pref parameter is also used to order those offers that match the constr so that the offers returned by the trader are in the order of greatest interest to the importer. If pref does not obey the syntax rules for a legal preference expression, then an IllegalPreference exception is raised. The policies parameter allows the importer to specify how the search should be performed as opposed to what sort of services should be found in the course of the search. This can be viewed as parameterizing the algorithms within the trader implementation. The policies are a sequence of name-value pairs. The names available to an importer depend on the implementation of the trader. However, some names are standardized where they effect the interpretation of other parameters or where they may impact linking and federation of traders. If a policy name in this parameter does not obey the syntactic rules for legal PolicyName?s, then an IllegalPolicyName exception is raised. If the type of the value associated with a policy differs from that specified in this specification, then a PolicyTypeMismatch exception is raised. If subsequent processing of a PolicyValue yields any errors (e.g., the starting_trader policy value is malformed), then an InvalidPolicyValue exception is raised. If the same policy name is included two or more times in this parameter, then the DuplicatePolicyName exception is raised. The desired_props parameter defines the set of properties describing returned offers that are to be returned with the object reference. There are three possibilities, the importer wants one of the properties, all of the properties (but without having to name them), or some properties (the names of which are provided). If any of the desired_props names do not obey the rules for identifiers, then an IllegalPropertyName exception is raised. If the same property name is included two or more times in this parameter, the DuplicatePropertyName exception is raised. The desired_props parameter may name properties which are not mandatory for the requested service type. If the named property is present in the matched service offer, then it shall be returned. The desired_props parameter does not affect whether or not a service offer is returned. To avoid missing desired properties, the importer should specify exists prop_name in the constraint. The returned offers are passed back in one of two ways (or a combination of both). The offers return result conveys a list of offers and the offer_itr is a reference to an interface at which offers can be obtained. The how_many parameter states how many offers are to be returned via the offers result, any remaining offers are available via the iterator interface. If the how_many exceeds the number of offers to be returned, then the offer_itr will be nil.. If any cardinality or other limits were applied by one or more traders in responding to a particular query, then the limits_applied parameter will contain the names of the policies which limited the query. The sequence of names returned in limits_applied from any federated or proxy queries must be concatenated onto the names of limits applied locally and returned.

Throws:
IllegalServiceType
UnknownServiceType
IllegalConstraint
IllegalPreference
IllegalPolicyName
PolicyTypeMismatch
InvalidPolicyValue
IllegalPropertyName
DuplicatePropertyName
DuplicatePolicyName