IT-SC book: Advanced CORBA® Programming with C++

If you know that a query is likely to return a large result and you require sorting, set match_card to the same value as search_card. These settings ensure that you will get the best possible sort for the offers that match.

If you limit search_card, you reduce the amount of data the trader must search, thereby improving performance. However, be aware that this practice may lead to incomplete answers. In the worst case, you will get no matching offers from the trader even though there are matching offers. This happens if no match is found with the first search_card offers examined by the trader.

If you use randomization and require only a single offer, set return_card to 1 and set both search_card and match_card to the largest permissible values. These settings give the best possible randomization. On the other hand, setting match_card < search_card results in better performance but in poorer randomization.

Ensure that the following relation holds for all queries:

•

• return_card <= match_card <= search_card

•

This is simply common sense. There is no point in asking for more offers to be returned or sorted than the number of offers searched.

Unfortunately, the specification is silent about how cardinality limits should be treated for federated traders (see Section 19.16.6). To learn about the behavior of your implementation, you must ask your trader vendor.

19.12 Bulk Withdrawal

The Register interface contains an operation to withdraw service offers in bulk:

interface Register : TraderComponents, SupportAttributes {

IllegalServiceType, UnknownServiceType, IllegalConstraint, NoMatchingOffers

);

// ...

};

The withdraw_using_constraint operation removes all service offers that match the constraint supplied in the constr parameter. The operation removes matching service offers of the type specified in the type parameter as well as those that are derived from the specified type (that is, the operation is polymorphic). You cannot suppress this polymorphic behavior because the operation does not have a policy parameter.

766

IT-SC book: Advanced CORBA® Programming with C++

You should exercise caution when using withdraw_using_constraint. It is easy to specify a constraint that is too loose and ends up removing more service offers than intended. However, it is one way to delete a service offer if you have lost the offer's ID. Recall from Section 19.8 that to withdraw a service offer, you need its offer ID. If you have lost the offer ID, withdraw_using_constraint can help provided that you can specify a constraint that is precise enough to match only the offer you want to delete.

Some traders mitigate the problem of lost offer IDs by adding an artificial property to each service offer that contains the offer's ID. The property can have an otherwise illegal name, such as _offer_id. (This is not a legal property name because it starts with an underscore.) The _offer_id property is normally invisible to clients and is not returned if a client imports service offers with the desired_props parameter set to all. However, if a client explicitly specifies the _offer_id property by providing its name in the desired_props parameter, the trader returns the property.

This extension allows you to recover the offer ID for existing service offers, but not all traders provide such a facility. Other traders offer administrative tools that allow you to examine the underlying database of the trader directly and recover a lost offer ID. Consult your vendor's documentation to see what facilities are provided.

19.13 The Admin Interface

The Admin interface contains operations to allow an administrator to configure policy values and to access the offer space directly.

19.13.1 Setting Configuration Values

The Admin interface contains operations to control configuration values:

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

767

IT-SC book: Advanced CORBA® Programming with C++

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); // ...

};

The set operations allow you to control values such as the maximum and default for the search_card, match_card, and return_card policies and the value of the max_list policy.

There are also operations to control the support level of a trader. The set_supports_modifiable_properties,set_supports_dynamic_pro perties, and set_supports_proxy_offers operations allow you to selectively enable or disable the corresponding feature. For example, you may want to disable support for dynamic properties because of reliability and performance considerations. Dynamic properties are necessarily less reliable because the trader depends on the correct working of objects not under its control for the evaluation of dynamic properties. Evaluation also requires remote calls from the trader to the objects supplying the property values, and this means that performance is not as good as with static properties.

The hop_count and follow_policy values relate to federation; we cover them in Section 16.16.1.

The set_type_repos operation allows you to set the object reference to the type repository returned by the type_repos attribute in the Lookup interface.

The set_request_id_stem operation controls an identifier that is used by the trader as a prefix for the ID of a federated query. This value must be unique for each trader in a federation and is used to prevent import loops (see Section 19.16.2). Typically, traders set this value only once—during installation—and never change it thereafter.

19.13.2 Retrieving Service Offer IDs

The Admin interface contains two additional operations to permit access to the complete offer space regardless of the type of service offers:

768

IT-SC book: Advanced CORBA® Programming with C++

interface Admin :

TraderComponents, SupportAttributes, ImportAttributes, LinkAttributes {

out OfferIdIterator id_itr ) raises(NotImplemented);

};

The list_offers operation returns all offer IDs in the trader database but omits proxy offers. The list_proxies operation, on the other hand, returns only the offer IDs for proxy offers and omits normal service offers. Both operations create an iterator object for large result sets:

interface OfferIdIterator {

};

The semantics of the iterator operations are the same as for a normal offer iterator (see Section 19.11.3) except that the returned sequences contain offer IDs instead of service offers.

19.14 Inspecting Service Offers

Given an offer ID, you can retrieve the details of the corresponding service offer:

interface Register : TraderComponents, SupportAttributes {

OfferInfo describe(in OfferId id) raises(

IllegalOfferId,

769