costrading.idl

UCS (Ultra Corba Simulator) is one more powerful corba client/servant simulator tool than other simi

/* docdef: costrade */
#ifndef COS_TRADING_IDL
#define COS_TRADING_IDL

#pragma prefix "omg.org"

/**
  * @author OMG
  * @version Version 1.0
  */

module CosTrading
{
   typedef Object TypeRepository;
   typedef string Istring;
   /* doc: 6 */	
   typedef Istring ServiceTypeName;
   /* enddoc */
   typedef Istring Constraint;
   typedef Istring PropertyName;
   typedef sequence <PropertyName> PropertyNameSeq;
   typedef any PropertyValue;
   typedef string OfferId;
   typedef sequence <OfferId> OfferIdSeq;
   typedef Istring LinkName;
   typedef sequence <LinkName> LinkNameSeq;
   typedef LinkNameSeq TraderName;
   typedef string PolicyName;
   typedef sequence <PolicyName> PolicyNameSeq;
   typedef any PolicyValue;

/** A service types describes a service supporting a
 * number of properties. Properties are a name/value tuples.
 * The value field holds both the type and value of a
 * property. Property types must correspond to the type defined
 * for the property by the corresponding service type.
 */

   struct Property
   {
      PropertyName name;
      PropertyValue value;
   };
   typedef sequence <Property> PropertySeq;

/** This structure contains information about an object exported
 * by the trader. It contains a reference to the object and
 * the properties that describe the object.
 */

   struct Offer
   {
      Object reference;
      PropertySeq properties;
   };
   typedef sequence <Offer> OfferSeq;

/** Policies determine trader behavior, for example, when
 * queries are evaluated. Policies exist to determine the
 * cardinality of offers and property matching criteria.
 */

   struct Policy
   {
      PolicyName name;
      PolicyValue value;
   };
   typedef sequence <Policy> PolicySeq;

/** This enum is used to determine the behaviour 
 * of the trader when traders are linked together.
 * <pre>
 * local_only	- Do not use other linked traders.
 * if_no_local	- Use linked traders if a query cannot be resolved locally.
 * always		- Always use linked traders.
 * </pre>
 */

   enum FollowOption
   {
      local_only,
      if_no_local,
      always
   };

   interface Lookup;
   interface Register;
   interface Link;
   interface Proxy;
   interface Admin;
   interface OfferIterator;
   interface OfferIdIterator;

   exception IllegalServiceType
   {
      ServiceTypeName type;
   };
   exception UnknownServiceType
   {
      ServiceTypeName type;
   };
   exception IllegalConstraint
   {
      Constraint constr;
   };
   exception IllegalOfferId
   {
      OfferId id;
   };
   exception IllegalPropertyName
   {
      PropertyName name;
   };
   exception InvalidLookupRef
   {
      Lookup target;
   };
   exception DuplicatePolicyName
   {
      PolicyName name;
   };
   exception DuplicatePropertyName
   {
      PropertyName name;
   };
   exception MissingMandatoryProperty
   {
      ServiceTypeName type;
      PropertyName name;
   };
   exception PropertyTypeMismatch
   {
      ServiceTypeName type;
      Property prop;
   };
   exception ReadonlyDynamicProperty
   {
      ServiceTypeName type;
      PropertyName name;
   };
   exception UnknownOfferId
   {
      OfferId id;
   };
   exception UnknownMaxLeft {};
   exception NotImplemented {};

/** This interface has references to the componet services
 * that make up a trader. Not all services may be present,
 * depending on the type of trader.
 */

   interface TraderComponents
   {
      readonly attribute Lookup lookup_if;
      readonly attribute Register register_if;
      readonly attribute Link link_if;
      readonly attribute Proxy proxy_if;
      readonly attribute Admin admin_if;
   };

/** This interface contains attributes that describe
 * type of functionality supported by a trader service.
 */

   interface SupportAttributes
   {
      readonly attribute boolean supports_modifiable_properties;
      readonly attribute boolean supports_dynamic_properties;
      readonly attribute boolean supports_proxy_offers;
      readonly attribute TypeRepository type_repos;
   };

/** This interface contains attributes that describe
 * policies used witin the trader when resolving queries.
 */

   interface ImportAttributes
   {
      readonly attribute unsigned long def_search_card;
      readonly attribute unsigned long max_search_card;
      readonly attribute unsigned long def_match_card;
      readonly attribute unsigned long max_match_card;
      readonly attribute unsigned long def_return_card;
      readonly attribute unsigned long max_return_card;
      readonly attribute unsigned long max_list;
      readonly attribute unsigned long def_hop_count;
      readonly attribute unsigned long max_hop_count;
      readonly attribute FollowOption def_follow_policy;
      readonly attribute FollowOption max_follow_policy;
   };

/** This interface contains attributes that describe
 * policies used witin the trader when following links
 * to other linked traders.
 */

   interface LinkAttributes
   {
      readonly attribute FollowOption max_link_follow_policy;
   };

/** This interface supports operations to iterate through
 * lists of OfferIds returned by the CosTrading::Admin
 * interface.
 */

   interface OfferIdIterator
   {
/** This operation returns the number of remaining
 * OfferIds contained within the iterator.
 *
 * @returns - The number of remaining OfferIds.
 * @raises UnknownMaxLeft - If the number of remaining OfferIds
 *                          cannot be determined. 
 */

      unsigned long max_left () raises (UnknownMaxLeft);

/** This operation returns up to a specified number
 * of remaining OfferIDs.
 *
 * @param n - The number of OfferIds to return.
 * @param ids - The sequence of returned OfferIds.
 * @returns - TRUE if there are more OfferIds to retrieve.
 */

      boolean next_n (in unsigned long n, out OfferIdSeq ids);

/** This operation destroys the OfferIDIterator and
 * and any OfferIds it contains. This should be called
 * after a client has finished with the iterator.
 */

      void destroy ();
   };

/** This interface supports operations to iterate through
 * lists of Offers returned by the CosTrading::Lookup::query
 * operation.
 */

   interface OfferIterator
   {
/** This operation returns the number of remaining
 * Offers contained within the iterator.
 *
 * @returns - The number of remaining offers.
 * @raises UnknownMaxLeft - If the number of remaining offers
 *                          cannot be determined. 
 */

      unsigned long max_left () raises (UnknownMaxLeft);

/** This operation returns up to a specified number
 * of remaining Offers.
 *
 * @param n - The number of Offers to return.
 * @param offers - The sequence of returned Offers.
 * @returns - TRUE if there are more Offers to retrieve.
 */

      boolean next_n (in unsigned long n, out OfferSeq offers);

/** This operation destroys the OfferIterator and
 * and any Offers it contains. This should be called
 * after a client has finished with the iterator.
 */

      void destroy ();
   };

/** This interface is used to query the trader and retrieve
 * offers which match specified conditions and constraints.
 */

   interface Lookup : TraderComponents, SupportAttributes, ImportAttributes
   {
      typedef Istring Preference;

/** This enum is used to determine whether to return
 * property information with returned offers.
 * <pre>
 * none	- Do not return properties.
 * some	- Return specified properties.
 * all	- Return all properties.
 * </pre>
 */

      enum HowManyProps
      {
         none,
         some,
         all
      };

/** This union is used in a query to determine which
 * properties should be retrieved with returned offers.
 * If some properties are to be retrieved these are
 * specified by name in a property name sequence.
 */

      union SpecifiedProps switch (HowManyProps)
      {
         case some : PropertyNameSeq prop_names;
         case none : short none_dummy;
         case all  : short all_dummy;
      };

      exception IllegalPreference
      {
         Preference pref;
      };
      exception IllegalPolicyName
      {
         PolicyName name;
      };
      exception InvalidPolicyValue
      {
         Policy the_policy;
      };
      exception PolicyTypeMismatch
      {
         Policy the_policy;
      };

/** This operation querys the trader for offers. The
 * various call parameters determine how the trader
 * finds offers to satisfy the query.
 *
 * @param type - The servivce type of the returned offers.
 * @param constr - The constraint string used for restricting
 *                 suitable offers.
 * @param pref - The preference string used to order returned
 *               offers.
 * @param policies - Policies used to override default trader
 *                   query policies.
 * @param desired_props - Specifies which properties to return
 *                        with offers.
 * @param how_many - The maximum number of offers to be returned.
 * @param offers - The sequence of returned offers.
 * @param offer_iter - A reference to an OfferIterator object
 *                     used to access offers not directly returned
 *                     in the offer sequence.
 * @param limit_applied - The limits applied by the trader while
 *                        processing the query.
 *
 * @raises IllegalServiceType - If the specified service type
 *                              name is invalid.
 * @raises UnknownServiceType - If the specified service type
 *                              has not been registered.
 * @raises IllegalConstraint - If the constraint string is invalid.
 * @raises IllegalPreference - If the preference string is invalid.
 * @raises IllegalPolicyName - If an invalid policy name was specified.
 * @raises PolicyTypeMismatch - If the type of a specified policy does
 *                              not match that of the specification.
 * @raises InvalidPolicyValue - If the value of a policy is invalid.
 * @raises IllegalPropertyName - If a property name is illegal.
 * @raises DuplicatePropertyName - If duplicate property names are specified.
 * @raises DuplicatePolicyName - If duplicate policy names are specified.
 */
      /* doc: 25 */