path: root/TAO/orbsvcs/orbsvcs/CosTrading.idl

/* -*- C++ -*- */

// ========================================================================
// $Id$
// 
// = FILENAME
//   CosTrading.idl
//
// = DESCRIPTION
//   Trader  Service v1.0 described in CORBAservices: Common Object
//   Services Specification, chapter 16 OMG IDL for Trading Function
//   Module, p 16-74
// 
// ========================================================================


module CosTrading {

	// forward references to our interfaces

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

	// type definitions used in more than one interface

	typedef string Istring;
	typedef Object TypeRepository;

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

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

	typedef string OfferId;
	typedef sequence<OfferId> OfferIdSeq;

	typedef Istring ServiceTypeName;  // similar structure to IR::Identifier

	typedef Istring Constraint;

	enum FollowOption {
		local_only, 
		if_no_local, 
		always
	};

	typedef Istring LinkName;
	typedef sequence<LinkName> LinkNameSeq;
	typedef LinkNameSeq TraderName;

	typedef string PolicyName;  // policy names restricted to Latin1
	typedef sequence<PolicyName> PolicyNameSeq;
	typedef any PolicyValue;
	struct Policy {
		PolicyName name;
		PolicyValue value;
	};
	typedef sequence<Policy> PolicySeq;

	// exceptions used in more than one interface

	exception UnknownMaxLeft {};

	exception NotImplemented {};

	exception IllegalServiceType {
		ServiceTypeName type;
	};

	exception UnknownServiceType {
		ServiceTypeName type;
	};

	exception IllegalPropertyName {
		PropertyName name;
	};

	exception DuplicatePropertyName {
		PropertyName name;
	};
	exception PropertyTypeMismatch {
		ServiceTypeName type;
		Property prop;
	};

	exception MissingMandatoryProperty {
		ServiceTypeName type;
		PropertyName name;
	};

	exception ReadonlyDynamicProperty {
		ServiceTypeName type;
		PropertyName name;
	};

	exception IllegalConstraint {
		Constraint constr;
	};

	exception InvalidLookupRef {
		Lookup target;
	};
	  
	exception IllegalOfferId {
		OfferId id;
	};

	exception UnknownOfferId {
		OfferId id;
	};

	exception DuplicatePolicyName {
		PolicyName name;
	};

	// the interfaces

	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;
	};

	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;
	};

	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;
	};

	interface LinkAttributes {

		readonly attribute FollowOption max_link_follow_policy;
	};

	interface Lookup:TraderComponents,SupportAttributes,ImportAttributes {

		typedef Istring Preference;

		enum HowManyProps { none, some, all };

		union SpecifiedProps switch ( HowManyProps ) {
			case some: PropertyNameSeq prop_names;
		};

		exception IllegalPreference {
			Preference pref;
		};

		exception IllegalPolicyName {
			PolicyName name;
		};

		exception PolicyTypeMismatch {
			Policy the_policy;
		};

		exception InvalidPolicyValue {
			Policy the_policy;
		};

		void query ( 
			in ServiceTypeName type,
			in Constraint constr,
			in Preference pref,
			in PolicySeq policies,
			in SpecifiedProps desired_props,
			in unsigned long how_many,
			out OfferSeq offers,
			out OfferIterator offer_itr,
			out PolicyNameSeq limits_applied
		) raises (
			IllegalServiceType,
			UnknownServiceType,
			IllegalConstraint,
			IllegalPreference,
			IllegalPolicyName,
			PolicyTypeMismatch,
			InvalidPolicyValue,
			IllegalPropertyName,
			DuplicatePropertyName,
			DuplicatePolicyName
		);
	};

	interface Register : TraderComponents, SupportAttributes {

		struct OfferInfo {
			Object reference;
			ServiceTypeName type;
			PropertySeq properties;
		};

		exception InvalidObjectRef {
			Object ref;
		};

		exception UnknownPropertyName {
			PropertyName name;
		};

		exception InterfaceTypeMismatch {
			ServiceTypeName type;
			Object reference;
		};

		exception ProxyOfferId {
			OfferId id;
		};

		exception MandatoryProperty {
			ServiceTypeName type;
			PropertyName name;
		};

		exception ReadonlyProperty {
			ServiceTypeName type;
			PropertyName name;
		};

		exception NoMatchingOffers {
			Constraint constr;
		};

		exception IllegalTraderName {
			TraderName name;
		};

		exception UnknownTraderName {
			TraderName name;
		};

		exception RegisterNotSupported {
			TraderName name;
		};

		OfferId export (
			in Object reference,
			in ServiceTypeName type,
			in PropertySeq properties
		) raises ( 
			InvalidObjectRef,
			IllegalServiceType,
			UnknownServiceType,
			InterfaceTypeMismatch, 
			IllegalPropertyName, // e.g. prop_name = "<foo-bar"
			PropertyTypeMismatch,
			ReadonlyDynamicProperty,
			MissingMandatoryProperty,
			DuplicatePropertyName
		);

		void withdraw (
			in OfferId id
		) raises (
			IllegalOfferId,
			UnknownOfferId,
			ProxyOfferId
		);

		OfferInfo describe (
			in OfferId id
		) raises (
			IllegalOfferId,
			UnknownOfferId,
			ProxyOfferId
		);

		void modify (
			in OfferId id,
			in PropertyNameSeq del_list,
			in PropertySeq modify_list
		) raises ( 
			NotImplemented,
			IllegalOfferId, 
			UnknownOfferId,
			ProxyOfferId,
			IllegalPropertyName,
			UnknownPropertyName,
			PropertyTypeMismatch,
			ReadonlyDynamicProperty,
			MandatoryProperty,
			ReadonlyProperty,
			DuplicatePropertyName
		);

		void withdraw_using_constraint (
			in ServiceTypeName type,
			in Constraint constr
		) raises (
			IllegalServiceType,
			UnknownServiceType,
			IllegalConstraint,
			NoMatchingOffers
		);

		Register resolve (
			in TraderName name
		) raises (
			IllegalTraderName,
			UnknownTraderName,
			RegisterNotSupported
		);
	};

	interface Link : TraderComponents, SupportAttributes, LinkAttributes {

		struct LinkInfo {
			Lookup target;
			Register target_reg;
			FollowOption def_pass_on_follow_rule;
			FollowOption limiting_follow_rule;
		};

		exception IllegalLinkName {
			LinkName name;
		};

		exception UnknownLinkName {
			LinkName name;
		};

		exception DuplicateLinkName {
			LinkName name;
		};
		exception DefaultFollowTooPermissive {
			FollowOption def_pass_on_follow_rule;
			FollowOption limiting_follow_rule;
		};

		exception LimitingFollowTooPermissive {
			FollowOption limiting_follow_rule;
			FollowOption max_link_follow_policy;
		};

		void add_link ( 
			in LinkName name,
			in Lookup target,
			in FollowOption def_pass_on_follow_rule,
			in FollowOption limiting_follow_rule
		) raises ( 
			IllegalLinkName,
			DuplicateLinkName,
			InvalidLookupRef, // e.g. nil
			DefaultFollowTooPermissive,
			LimitingFollowTooPermissive
		);

		void remove_link (
			in LinkName name
		) raises (
			IllegalLinkName,
			UnknownLinkName
		);

		LinkInfo describe_link (
			in LinkName name
		) raises (
			IllegalLinkName,
			UnknownLinkName
		);

		LinkNameSeq list_links ( );

		void modify_link ( 
			in LinkName name,
			in FollowOption def_pass_on_follow_rule,
			in FollowOption limiting_follow_rule
		) raises ( 
			IllegalLinkName,
			UnknownLinkName,
			DefaultFollowTooPermissive,
			LimitingFollowTooPermissive
		);
	};

	interface Proxy : TraderComponents, SupportAttributes {

		typedef Istring ConstraintRecipe;

		struct ProxyInfo { 
			ServiceTypeName type;
			Lookup target;
			PropertySeq properties;
			boolean if_match_all;
			ConstraintRecipe recipe;
			PolicySeq policies_to_pass_on;
		};

		exception IllegalRecipe {
			ConstraintRecipe recipe;
		};

		exception NotProxyOfferId {
			OfferId id;
		};

		OfferId export_proxy (
			in Lookup target,
			in ServiceTypeName type,
			in PropertySeq properties,
			in boolean if_match_all,
			in ConstraintRecipe recipe,
			in PolicySeq policies_to_pass_on
		) raises (
			IllegalServiceType,
			UnknownServiceType,
			InvalidLookupRef, // e.g. nil
			IllegalPropertyName,
			PropertyTypeMismatch,
			ReadonlyDynamicProperty,
			MissingMandatoryProperty,
			IllegalRecipe,
			DuplicatePropertyName,
			DuplicatePolicyName
		);

		void withdraw_proxy (
			in OfferId id
		) raises (
			IllegalOfferId,
			UnknownOfferId,
			NotProxyOfferId
		);

		ProxyInfo describe_proxy (
			in OfferId id
		) raises (
			IllegalOfferId,
			UnknownOfferId,
			NotProxyOfferId
		);
	};

	interface Admin : TraderComponents, SupportAttributes, ImportAttributes,
						LinkAttributes {

		typedef sequence<octet> OctetSeq;

		readonly attribute OctetSeq request_id_stem;

		unsigned long set_def_search_card (in unsigned long value);
		unsigned long set_max_search_card (in unsigned long value);

		unsigned long set_def_match_card (in unsigned long value);
		unsigned long set_max_match_card (in unsigned long value);

		unsigned long set_def_return_card (in unsigned long value);
		unsigned long set_max_return_card (in unsigned long value);

		unsigned long set_max_list (in unsigned long value);

		boolean set_supports_modifiable_properties (in boolean value);
		boolean set_supports_dynamic_properties (in boolean value);
		boolean set_supports_proxy_offers (in boolean value);

		unsigned long set_def_hop_count (in unsigned long value);
		unsigned long set_max_hop_count (in unsigned long value);

		FollowOption set_def_follow_policy (in FollowOption policy);
		FollowOption set_max_follow_policy (in FollowOption policy);

		FollowOption set_max_link_follow_policy (in FollowOption policy);

		TypeRepository set_type_repos (in TypeRepository repository);

		OctetSeq set_request_id_stem (in OctetSeq stem);

		void list_offers (
			in unsigned long how_many,
			out OfferIdSeq ids,
			out OfferIdIterator id_itr
		) raises (
			NotImplemented
		);

		void list_proxies (
			in unsigned long how_many,
			out OfferIdSeq ids,
			out OfferIdIterator id_itr
		) raises (
			NotImplemented
		);
	};

	interface OfferIterator {

		unsigned long max_left (
		) raises (
			UnknownMaxLeft
		);

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

		void destroy ();
	};

	interface OfferIdIterator {
		unsigned long max_left (
		) raises (
			UnknownMaxLeft
		);

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

		void destroy ();
	};

}; /* end module CosTrading */


// OMG IDL for Dynamic Property  Module, p 16-88

module CosTradingDynamic {

	exception DPEvalFailure {
		CosTrading::PropertyName name;
		TypeCode returned_type;
		any extra_info;
	};

	interface DynamicPropEval {

		any evalDP (
			in CosTrading::PropertyName name,
			in TypeCode returned_type,
			in any extra_info
		) raises (
			DPEvalFailure
		);
	};

	struct DynamicProp {
		 DynamicPropEval eval_if;
		 TypeCode returned_type;
		 any extra_info;
	};
}; /* end module CosTradingDynamic */


// OMG IDL for Service Type Repository Module, p 16-89

module CosTradingRepos {

	interface ServiceTypeRepository {

	// local types
		typedef sequence<CosTrading::ServiceTypeName> ServiceTypeNameSeq;
		enum PropertyMode {
			PROP_NORMAL, PROP_READONLY,
			PROP_MANDATORY, PROP_MANDATORY_READONLY
		};
		struct PropStruct {
			CosTrading::PropertyName name;
			TypeCode value_type;
			PropertyMode mode;
		};
		typedef sequence<PropStruct> PropStructSeq;

		typedef CosTrading::Istring Identifier;  // IR::Identifier
		struct IncarnationNumber {
			unsigned long high;
			unsigned long low;
		};
		struct TypeStruct {
			Identifier if_name;
			PropStructSeq props;
			ServiceTypeNameSeq super_types;
			boolean masked;
			IncarnationNumber incarnation;
		};

		enum ListOption { all, since };
		union SpecifiedServiceTypes switch ( ListOption ) {
			case since: IncarnationNumber incarnation;
		};

	// local exceptions
		exception ServiceTypeExists {
			CosTrading::ServiceTypeName name;
		};
		exception InterfaceTypeMismatch {
			CosTrading::ServiceTypeName base_service;
			Identifier base_if;
			CosTrading::ServiceTypeName derived_service;
			Identifier derived_if;
		};
		exception HasSubTypes {
			CosTrading::ServiceTypeName the_type;
			CosTrading::ServiceTypeName sub_type;
		};
		exception AlreadyMasked {
			CosTrading::ServiceTypeName name;
		};
		exception NotMasked {
			CosTrading::ServiceTypeName name;
		};
		exception ValueTypeRedefinition {
			CosTrading::ServiceTypeName type_1;
			PropStruct definition_1;
			CosTrading::ServiceTypeName type_2;
			PropStruct definition_2;
		};
		exception DuplicateServiceTypeName {
			CosTrading::ServiceTypeName name;
		};

	// attributes
		readonly attribute IncarnationNumber incarnation;

	// operation signatures
		IncarnationNumber add_type (
			in CosTrading::ServiceTypeName name,
			in Identifier if_name,
			in PropStructSeq props,
			in ServiceTypeNameSeq super_types
		) raises (
			CosTrading::IllegalServiceType,
			ServiceTypeExists,
			InterfaceTypeMismatch,
			CosTrading::IllegalPropertyName,
			CosTrading::DuplicatePropertyName,
			ValueTypeRedefinition,
			CosTrading::UnknownServiceType,
			DuplicateServiceTypeName
		);
				
		void remove_type (
			in CosTrading::ServiceTypeName name
		) raises (
			CosTrading::IllegalServiceType,
			CosTrading::UnknownServiceType,
			HasSubTypes
		);

		ServiceTypeNameSeq list_types (
			in SpecifiedServiceTypes which_types
		);

		TypeStruct describe_type (
			in CosTrading::ServiceTypeName name
		) raises (
			CosTrading::IllegalServiceType,
			CosTrading::UnknownServiceType
		);

		TypeStruct fully_describe_type (
			in CosTrading::ServiceTypeName name
		) raises (
			CosTrading::IllegalServiceType,
			CosTrading::UnknownServiceType
		);

		void mask_type (
			in CosTrading::ServiceTypeName name
		) raises (
			CosTrading::IllegalServiceType,
			CosTrading::UnknownServiceType,
			AlreadyMasked
		);

		void unmask_type (
			in CosTrading::ServiceTypeName name
		) raises (
			CosTrading::IllegalServiceType,
			CosTrading::UnknownServiceType,
			NotMasked
		);

	};
}; /* end module CosTradingRepos */