/* * System: TIHP * * Module(s): TIHP, TIHP::Data, TIHP::Meta, TIHP::Setup * * Language/Build: CORBA IDL 2.1 * * Description: The IDL for the TIH Publisher * * Modification History: * * Date Who SCJS No. Remarks * 28/09/00 RC Created * 01/03/01 RC Corrected Typo's * 10/04/01 RC Altered selection tree to handle null values * 12/06/01 RC Fixed idenifier problem for SEA. * 12/06/01 RC 001 Issue * */ module TIHP { module Data { typedef sequence BooleanSeq; typedef sequence OctetSeq; typedef sequence CharSeq; typedef sequence Int16Seq; typedef sequence Nat16Seq; typedef sequence Int32Seq; typedef sequence Nat32Seq; typedef sequence FloatSeq; typedef sequence DoubleSeq; typedef sequence StringSeq; typedef sequence BooleanSeqSeq; typedef sequence OctetSeqSeq; typedef sequence CharSeqSeq; typedef sequence Int16SeqSeq; typedef sequence Nat16SeqSeq; typedef sequence Int32SeqSeq; typedef sequence Nat32SeqSeq; typedef sequence FloatSeqSeq; typedef sequence DoubleSeqSeq; typedef sequence StringSeqSeq; enum ValueTypes { SUPER_CLASS, REFERENCE, REFERENCE_SEQ, BOOLEAN_VALUE, OCTET_VALUE, CHAR_VALUE, INT16_VALUE, NAT16_VALUE, INT32_VALUE, NAT32_VALUE, FLOAT_VALUE, DOUBLE_VALUE, STRING_VALUE, BOOLEAN_SEQ_VALUE, OCTET_SEQ_VALUE, CHAR_SEQ_VALUE, INT16_SEQ_VALUE, NAT16_SEQ_VALUE, INT32_SEQ_VALUE, NAT32_SEQ_VALUE, FLOAT_SEQ_VALUE, DOUBLE_SEQ_VALUE, STRING_SEQ_VALUE }; union ColumnData switch (ValueTypes) { case SUPER_CLASS: Nat16Seq entry; case REFERENCE: Nat16Seq reference; case REFERENCE_SEQ: Nat16SeqSeq references; case BOOLEAN_VALUE: BooleanSeq boolean_; case OCTET_VALUE: OctetSeq octet_; case CHAR_VALUE: CharSeq char_; case INT16_VALUE: Int16Seq int16_; case NAT16_VALUE: Nat16Seq nat16_; case INT32_VALUE: Int32Seq int32_; case NAT32_VALUE: Nat32Seq nat32_; case FLOAT_VALUE: FloatSeq float_; case DOUBLE_VALUE: DoubleSeq double_; case STRING_VALUE: StringSeq string_; case BOOLEAN_SEQ_VALUE: BooleanSeqSeq booleanSeq_; case OCTET_SEQ_VALUE: OctetSeqSeq octetSeq_; case CHAR_SEQ_VALUE: CharSeqSeq charSeq_; case INT16_SEQ_VALUE: Int16SeqSeq int16Seq_; case NAT16_SEQ_VALUE: Nat16SeqSeq nat16Seq_; case INT32_SEQ_VALUE: Int32SeqSeq int32Seq_; case NAT32_SEQ_VALUE: Nat32SeqSeq nat32Seq_; case FLOAT_SEQ_VALUE: FloatSeqSeq floatSeq_; case DOUBLE_SEQ_VALUE: DoubleSeqSeq doubleSeq_; case STRING_SEQ_VALUE: StringSeqSeq stringSeq_; }; struct AttributeColumn { ColumnData values; Nat16Seq nullMap; boolean invertNullMap; }; typedef sequence ClassTable; typedef sequence ClassTableSeq; struct TransportBlock { Nat16Seq classIds; Nat16Seq entryIds; ClassTableSeq classes; }; }; module Meta { struct AttributeInfo { /** The name of the attribute */ string name; /** The attribute type */ Data::ValueTypes type; /** Specifies if this attribute is optional, i.e. can be null */ boolean isOptional; /** * The name of the class that this attribute refernces or that * this class inherits from. If this is a vlaue attribute this */ string className; }; typedef sequence AttributeInfoSeq; struct ClassInfo { string name; AttributeInfoSeq attributes; }; typedef sequence ClassInfoSeq; }; module Setup { enum LeafParameterTypes {ATTRIBUTE_PARAM, VALUE_PARAM}; enum NodeTypes {BINARY_NODE, UNARY_NODE, BINARY_LEAF_NODE, UNARY_LEAF_NODE}; enum BinaryOps {AND_OP, OR_OP}; enum UnaryOps {NOT_OP}; enum BinaryLeafOps { EQUAL_TO, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL_TO, LESS_THAN_OR_EQUAL_TO, NOT_EQUAL_TO }; enum UnaryLeafOps {IS_NULL_OP}; union LeafParameter switch (LeafParameterTypes) { case ATTRIBUTE_PARAM : string attributeName; case VALUE_PARAM : any value; }; union SelectionTree switch (NodeTypes) { /** * Binary nodes must always have two children. */ case BINARY_NODE : struct BinaryNode { BinaryOps op; sequence children; } bNode; /** * Unary nodes must always have one child. */ case UNARY_NODE : struct UnaryNode { UnaryOps op; sequence child; } uNode; /** * The left and right parameters should be of the same type. */ case BINARY_LEAF_NODE : struct BinaryLeafNode { LeafParameter left; BinaryLeafOps op; LeafParameter right; } bLeaf; /** * Unary leaf nodes can be applied to any parameter. */ case UNARY_LEAF_NODE : struct UnaryLeafNode { UnaryLeafOps op; LeafParameter parameter; } uLeaf; }; struct SelectionAttributeInfo { /** The name of the selection attribute */ string name; /** The type of the selection attribute */ CORBA::TypeCode type; }; typedef sequence SelectionAttributeInfoSeq; }; exception MethodTimeoutException {}; exception NotSubscribedException {}; exception ConcurrentPullException {}; exception NoSuchServiceException {}; exception InvalidLoginException {}; exception TooManyUsersException {}; exception NoSubscriptionsException {}; exception RNMDException {}; exception MethodAbortedException {}; exception PullSessionStillActiveException {}; exception TooManyNodesException {}; exception ValueOutOfRangeException { /** The value that was out of range. */ any value; /** The lower bound for valid values.*/ any lower; /** The upper bound for valid values.*/ any upper; }; exception LoginRefusedException { /** The reason why the client's login was refused. */ string reason; }; exception BadPasswordException { /** The reason why the given password was bad. */ string reason; }; exception InvalidSelectionTreeException { /** The address of the invalid node. */ Data::OctetSeq address; /** The reason that the selection tree was invalid. */ string reason; }; interface PullSession { /** * This method is used to pull another transport block from the * TIHP. The method returns true when it has not pulled all the * data available on the server, for example if the object limit * has been reached. This is to indicate that the client should * pull again as soon as possible to avoid a backlog. *
* The sync parameter is to ensure that the server sends the * correct transport block each pull. On the first pull the * client sends the initial value to the server, on all subsequent * pulls the last sync value sent back to the client is resent to * the server. If the server receives a sync value that is not * the one it sent to the client last time then it knows that it * should re-send the last transport block as it was not received. * By using this mechanism the client doesn't have to write * complex exception handling to determine if it should repeat the * last failed pull, it just has to send the last value that the * server sent back. * * @param block the transport block containing objects from * subscribed services. * @param sync the client / server synchronisation value. * * @return true if there is still data available on the TIHP, * false otherwise. * * @throws ConcurrentPullException if there is already a pull * method invocation blocking on this object. * @throws NoSubscriptionsException if the client has no current * subscriptions. * @throws RNMDException if the TIHP could not communicate with * the RNMD. * @throws MethodAbortedException if Session::abortBlockedMethods() * was called by another thread. * @throws MethodTimeoutException if this method has exceeded the * current blocking method timeout. */ boolean pull(out Data::TransportBlock block, inout boolean sync) raises (ConcurrentPullException, NoSubscriptionsException, RNMDException, MethodAbortedException, MethodTimeoutException); /** * The method will end the current pull session. The PullSession * object is disconnected from the ORB and its resources * reclaimed. After this method has completed then is possible to * create another pull session. A ConcurrentPullException is * raised if the method is invoked during a blocked pull. * * @throws ConcurrentPullException if this method was invoked * during a blocked pull on the same object. */ void endSession() raises (ConcurrentPullException); /** * This method returns the names of the services that the client * is currently subscribed to. * * @return The names of all the services that the client is * currently subscribed to. */ Data::StringSeq getSubscriptions(); /** * This method will return the current transport layout. * * @returns The layout of the transport blocks. */ Meta::ClassInfoSeq getLayout(); /** * This method will drop the subscription to the specified service. * A ConcurrentPullException is raised if the method is invoked * during a blocked pull. * * @param serviceName the name of the service that the client * wishes to unsubscribe from. * * @throws NotSubscribedException if client was not subscribed to * the specified exception. * @throws ConcurrentPullException if this method was invoked * during a blocked pull on the same object. */ void unsubscribe(in string serviceName) raises (NotSubscribedException, ConcurrentPullException); /** * This method will remove any unused classes in the transport * data structure. If the layout of the transport data structure * has changed then this method returns true, false if not. If the * transport layout has changed then the PullSession::getLayout() * method should be used to obtain the new transport layout. *
* This method would typically be used after the client has * dropped a number of services to achieve more compact transport * blocks. * * @returns true if the layout of the transport data structure has * changed, false otherwise. * * @throws ConcurrentPullException if this method was invoked * during a blocked pull on the same object. */ boolean compactLayout() raises (ConcurrentPullException); /** * This method passes the current, minimum and maximum object * limits for a transport block back to the client. * * @param current the current object limit. * @param min the minimum object limit allowed. * @param max the maximum object limit allowed. */ void getObjectLimit(out unsigned short current, out unsigned short min, out unsigned short max); /** * This method sets a new limit to the number of objects that a * transport block may contain. The specified limit must lie * within the minimum and maximum bounds returned by the * PullSession::getObjectLimit() method if not a * ValueOutOfRangeException is raised. * * @param limit the new object limit. * * @throws ValueOutOfRangeException if the value passed was too * large or too small. */ void setObjectLimit(in unsigned short limit) raises (ValueOutOfRangeException); }; interface PullSetup { /** * This method returns a sequence of strings containing the names * of the services that are currently available on the TIHP. * * @return The names of the currently available services. */ Data::StringSeq getServiceNames(); /** * This method will subscribe the client to the specified service. * If the specified service is not available on the TIHP then a * NoSuchServiceException is raised. If the client has already * subscribed to the specified service then the invocation of this * method will result in any selection criteria from being removed. * * @param serviceName the name of the service that the client * wishes to subscribe to. * * @throws NoSuchServiceException if the client tries to subscribe * to a service that is not currently available. */ void subscribe(in string serviceName) raises (NoSuchServiceException); /** * This method returns a sequence containing information about the * selection attributes of a service. Every SelectionAttributeInfo * structure in the sequence represents a different selection * attribute. From these structures the client can determine the * name and type of each selection attribute. If the specified * service is not available on the TIHP then a * NoSuchServiceException is raised. * * @param serviceName the name of the service. * @param maxNodes the maximum number of nodes in a selection * tree that the specified services will accept. * @param attributes the available selection attributes for the * specified service. * * @throws NoSuchServiceException if serviceName is not the name * of a currently available service. */ void getSelectionInfo(in string serviceName, out short maxNodes, out Setup::SelectionAttributeInfoSeq attributes) raises (NoSuchServiceException); /** * This method allows the client to set the selection criteria * for a specified service. If the specified service name doesn't * relate to a service provided by the TIHP, then a * NoSuchServiceException is raised. This method will subscribe * the client to the service if they do not already have a * subscription. If the specified selection tree has a greater * number of nodes than the maximum permitted number then a * TooManyNodesException is raised. An InvalidSelectionTreeException * is raised if an invalid selection tree was passed. This exception * will contain the reason and the address of the invalid node. * * @param serviceName the name of the service. * @param criteria the tree that defines the required selection * criteria for items within the specified service. * * @throws NoSuchServiceException if serviceName is not the name * of a currently available service. * @throws TooManyNodesException if tree had a number of nodes * that exceeded the limit for the specified service. * @throws InvalidSelectionTree if the tree was invalid in someway. */ void setSelectionCriteria(in string serviceName, in Setup::SelectionTree criteria) raises (NoSuchServiceException, InvalidSelectionTreeException, TooManyNodesException); /** * This method will create a new PullSession object using the * current subscription information sent to this PullSetup object * and return the client a reference to it. The PullSetup object * will be disconnected from the ORB and its resources reclaimed * by this method. * * @return A new PullSession object that the client may use extract * data from the services it has subscribed to. */ PullSession startPullSession(); }; interface Session { /** * This method is used to obtain a PullSetup object from the TIHP. * Clients are currently only allowed one pull session active at * a time, so they must end any current pull session before they * start another. * * @return A PullSetup object. * * @throws PullSessionStillActiveException if the client has a * PullSession object that has not been destroyed. */ PullSetup setupPullSession() raises (PullSessionStillActiveException); /** * A client will use this method to change its login password. * The password must be at least 8 characters long and should * contain a numerical, uppercase and lower case character. The * password is only changed if the method completes normally. * * @param newPassword the new password for this user. * * @throws BadPasswordException if the password provided did not * fit the password requirements. * @throws RNMDException if the TIHP could not write the new * password to the RNMD. */ void changePassword(in string newPassword) raises (BadPasswordException, RNMDException); /** * This method ends the current session. It causes the object to * be disconnected from the ORB and its resources reclaimed. * Any child objects will also be disconnected and their resources * reclaimed. */ void endSession(); /** * This method returns the current, minimum and maximum idle * timeout in milliseconds. Note the minimum idle timeout is always * greater than the current blocked method timeout. As such if the * blocked method timeout is changed then the minimum idle timeout * will also change. This is to ensure that a blocked method will * timeout before the session does. * * @param current the current idle timeout in milliseconds. * @param min the minimum idle timeout allowed. * @param max the maximum idle timeout allowed. */ void getIdleTimeout(out long current, out long min, out long max); /** * This method is used to set the client session idle timeout. * If the value provided is either too small or too large a * ValueOutOfRangeException will be raised. The minimum and maximum * times allowed can be obtained from the Session::getIdleTimeout() * method. This method will cause any currently blocking methods to * timeout. * * @param milliseconds the new idle timeout in milliseconds. * * @throws ValueOutOfRangeException if the value passed was too * large or too small. */ void setIdleTimeout(in long milliseconds) raises (ValueOutOfRangeException); /** * This method returns the current, minimum and maximum blocking * method timeout in milliseconds. The maximum blocked method * timeout will always be less than the current idle timeout. * * @param current the current blocked method timeout in milliseconds. * @param min the minimum blocked method timeout allowed. * @param max the maximum blocked method timeout allowed. */ void getMethodTimeout(out long current, out long min, out long max); /** * This method is used to set the blocking method timeout. If the * value provided is either too small or too large a * ValueOutOfRangeException will be raised. The minimum and maximum * times allowed can be obtained from the Session::getMethodTimeout() * method. Changes to the blocked method timeout can result in * changes to the minimum idle timeout. * * @param milliseconds the new blocking method timeout in * milliseconds. * * @throws ValueOutOfRangeException if the value passed was too * large or too small. */ void setMethodTimeout(in long milliseconds) raises (ValueOutOfRangeException); /** * This method will cause any currently blocked method to abort and * raise a MethodAbortedException. This method will return false if * there were no blocking methods to abort. * * @return true if any blocking methods where aborted, * false otherwise. */ boolean abortBlockedMethods(); }; interface TIHPLogin { /** * This method is used to create a session on the TIHP. * As there is a limit to the number of concurrent users that the * TIHP is required to handle, login attempts will be refused once * this limit has been reached. Clients are only permitted to have * one active session at a time so any attempt to create another * session before a former session has ended will be refused. * * @param username the client's username. * @param password the client's password. * * @return a Session object * * @throws TooManyUsersException if TIHP has reached the maximum * number of concurrent users (100 max). * @throws InvalidLoginException if the client provided an invalid * username and password combination. * @throws LoginRefusedException if the client login has been * refused for another reason e.g. already has a * session active. */ Session login(in string username, in string password) raises (TooManyUsersException, InvalidLoginException, LoginRefusedException); }; };