//File: CosTrading.idl
//Part of the Trading Object Service

#ifndef _COS_TRADING_IDL_
#define _COS_TRADING_IDL_

#pragma prefix "omg.org"

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 */

#endif /* ifndef _COS_TRADING_IDL_ */