Sybase NNTP forums - End Of Life (EOL)

The NNTP forums from Sybase - forums.sybase.com - are now closed.

All new questions should be directed to the appropriate forum at the SAP Community Network (SCN).

Individual products have links to the respective forums on SCN, or you can go to SCN and search for your product in the search box (upper right corner) to find your specific developer center.

user-spawned threads in Jaguar & "com.sybase.ejb.local"

2 posts in General Discussion (old) Last posting was on 2000-03-09 20:20:50.0Z
Andrew Oxenburgh Posted on 2000-03-09 18:09:50.0Z
Newsgroups: sybase.public.easerver
From: "andrew oxenburgh" <andrew.oxenburgh@gartmore.com>
Organization: 194.223.39.65
X-Newsreader: AspNNTP 1.41 (Advent 2000, Inc.)
Subject: user-spawned threads in Jaguar & "com.sybase.ejb.local"
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Date: Thu, 09 Mar 2000 13:09:50 -0500
Lines: 34
NNTP-Posting-Host: 207.156.232.4
Message-ID: <347_vDLPpKfi$GA.251@forums.sybase.com>
Path: forums-1-dub!forums-1-dub!forums-master.sybase.com!forums.sybase.com
Xref: forums-1-dub sybase.public.easerver:26772
Article PK: 157747

Hi,

We're setting up a message processor using Jaguar, and we require a
multi-threaded element to our system.

What we want are many user defined threads, which create worker beans. The
threads read off a queue and pass the message on to these beans, which then
process the message.

------------------------------

Going through the Jaguar CTS3.5 Programmers manual, the section on creating
EJB's, and the subsection about interface proxies, there is a bit about the
environment property, "com.sybase.ejb.local", which says:

"For server-side component use only. Specifies whether the proxy references can
be used to issue intercomponent calls in user-spawned threads. The default is
"true," which means that intercomponent calls are made in memory and must be
issued from a thread spawned by Jaguar. Set this property to "false" if your
component makes intercomponent calls from user-spawned threads."

------------------------------

Can anyone clarify this for me?

1. Do I have to set "com.sybase.ejb.local" to false?

2. If I do, what are the further implications of clearing this flag?

3. Is it inherently unwise to use user-spawned threads in Jaguar

thank you, andrewo

---== Posted via the PFCGuide Web Newsreader ==---
http://www.pfcguide.com/_newsgroups/group_list.asp


Evan Ireland Posted on 2000-03-09 20:20:50.0Z
Newsgroups: sybase.public.easerver
Date: Fri, 10 Mar 2000 09:20:50 +1300
From: Evan Ireland <eireland@sybase.com>
Organization: Sybase, Inc.
X-Mailer: Mozilla 4.7 [en] (WinNT; U)
X-Accept-Language: en
MIME-Version: 1.0
To: andrew oxenburgh <andrew.oxenburgh@gartmore.com>
Subject: Message Service (was Re: user-spawned threads in Jaguar & "com.sybase.ejb.local")
Content-Type: multipart/mixed; boundary="------------D7058C167A9EB306C9B96FB4"
Lines: 1315
NNTP-Posting-Host: vpn-eme-043.sybase.com 130.214.8.43
Message-ID: <347_38C807A2.537DB152@sybase.com>
References: <347_vDLPpKfi$GA.251@forums.sybase.com>
Path: forums-1-dub!forums-1-dub!forums-master.sybase.com!forums.sybase.com
Xref: forums-1-dub sybase.public.easerver:26753
Article PK: 157737

Interface Repository Interface CtsComponents::MessageService

The message service provides queues for message consumers, and allows a message producers to send messages to specified queues (point-to-point messaging), or to publish messages with specified topics that may be of interest to registered consumers (publish/subscribe messaging).

Messages that are sent or published to a queue are stored in memory (transient messages) or in a database (persistent messages) until they can be delivered to the queue's consumer, which is either a client or a component. The message service provides a pull-style mechanism for client notification, and a push-style mechanism for component notification.

Once configuration is complete, the message service can be accessed by CORBA 2.0+ clients with IIOP 1.0 or IIOP 1.1 using this CORBA IDL interface, or by Java/EJB clients using the Java Message Service (JMS) API.

Key Features
  • Java Message Service
  • Administration Tool
  • High Availability
  • Load Balancing
  • Message Security
  • Queued Methods
  • Reliable Delivery
  • Scalable Notification
  • Transaction Management
Outstanding Issues

The following issues need to be resolved for production release.

Planned Resolution DateIssue Description After GA The syntax for selector expressions is not documented. Please refer to the selector expression syntax in the JMS specification in the interim. After GA The documentation for the PropertyValue type does not show the constant names in the case clauses (only the values are shown). The HTML documentation generator needs modification to generate the constant names. After GA The JMS provider (package com.sybase.jms) is not implemented. Maui (Q3 2000) The administration tool is not integrated into Sybase Central. Maui (Q3 2000) CR# 211239: The PowerBuilder VM does not handle marshalling correctly for IDL union types. The union type PropertyValue is used in the Message type. Maui (Q3 2000) CR# 211240: COM/ActiveX proxy generation does not handle IDL union types. The union type PropertyValue is used in the Message type. Maui (Q3 2000) Queued Methods are not implemented. Maui (Q3 2000) IIOP/SSL is not implemented natively by the message queue IIOP handler. The server allocates more threads for clients accessing message queues using a "qop" (Quality of Protection) property that requires SSL. Native SSL support in the message queue IIOP handler will reduce server resource utilization for clients using IIOP/SSL.

Operation Index
  • addListener
  • addRole
  • addSelector
  • getListeners
  • getMessageKey
  • getMessageQueue
  • getNames
  • getProperties
  • getRoles
  • getSelectors
  • getStatistics
  • getUniqueName
  • publish
  • removeListener
  • removeRole
  • removeSelector
  • send
  • setProperties
Operations
  • addListener

    Add a message listener for a queue, optionally giving the name of a thread pool, which has been configured with one or more worker threads. If unspecified, the thread pool defaults to the system default thread pool which has a single worker thread.

    void addListener ( in string queue, in string listener );

    Save the listener to persistent storage unless the queue is temporary.

    The listener is either a component name or it is a stringified IOR for an object that implements the MessageListener interface.

    Example 1: process messages for queue "MyClient:email" by calling the onMessage method on the "MyPackage/MailService" component.

    MessageService cms = getMessageService(); cms.addListener("MyClient:email", "MyPackage/MailService");

    Example 2: same as above but redirect the messages to another queue for which a thread pool has been configured.

    MessageService cms = getMessageService(); cms.addListener("MyClient:email", "MyPackage/MailService[work]");

  • addRole

    Add a required role for accessing name.

    void addRole ( in long type, in string name, in string role );

    The type parameter is a bit mask composed of one of: MESSAGE_QUEUE, MESSAGE_TOPIC, and one of CONSUMER, PRODUCER, SECURITY.

    The name parameter is a queue or topic name.

    • The name may be "*:suffix" (for queues) to install a role required for all queues with the specified suffix.
    • The name may be "*" (for queues and topics) to install a default role required for queues or topics that don't have specific roles assigned.
    • The name may end with ".*" (for topics) to install a default role required for sub-topics that don't have specific roles assigned.

    The role parameter is a role name. If more than one role is added to a queue or topic, a client needs to possess only one of those roles to access the queue or topic. If no roles are assigned to a queue or topic, then any client will be able to access it.

    Example 1: add a role "MyRole" that is required for receiving messages from queue "MyQueue".

    MessageService cms = getMessageService(); cms.addRole(MESSAGE_QUEUE.value + CONSUMER.value, "MyQueue", "MyRole");

    Example 2: add a role "Broker Role" that is required for publishing messages to topics with names beginning with "stock.".

    MessageService cms = getMessageService(); cms.addRole(MESSAGE_TOPIC.value + PRODUCER.value, "stock.*", "Broker Role");

    Example 3: add a role "Stock Topic Admin Role" that is required for managing security for topics with names beginning with "stock.".

    MessageService cms = getMessageService(); cms.addRole(MESSAGE_TOPIC.value + SECURITY.value, "stock.*", "Stock Topic Admin Role");

    Note: to add SECURITY type roles, the calling client must already have SECURITY access to the entity concerned, or otherwise the calling client must be a server administrator.

  • addSelector

    Add a message selector for a queue. Save the selector to persistent storage unless the queue is temporary. Note: for temporary queues, the selector(s) should be added to the queue after getMessageQueue is called.

    void addSelector ( in string queue, in string selector );

    The selector is an expression that conforms to the JMS (Java Message Service) selector specification, i.e. a subset of SQL-92 syntax, usually with an added clause to test equality of the topic property, i.e. subscribing to the topic.

    Subject to security checks, it is possible to add a selector that has no equality condition on the topic property. For example, a selector of "TRUE" will match every published message, no matter what the topic.

    Example - request notification of a new stock value:

    MessageService cms = getMessageService(); cms.addSelector("MyClient:stock", "topic = 'stock.SYBS' AND value > 50");

  • getListeners

    Return all of the message listeners for a queue. See addListener.

    CtsComponents::StringSeq getListeners ( in string queue );

  • getMessageKey

    Return a unique message key for a new message. This is used when creating a message to send or publish.

    CtsComponents::MessageKey getMessageKey ( );

    See also: key16.

  • getMessageQueue

    Get a message queue object that a client can use to acknowledge, list or receive messages in queue.

    CtsComponents::MessageQueue getMessageQueue ( in string queue, in string config, in long options );

    The queue name is usually the client user name, or the client user name followed by a colon and an arbitrary suffix. A queue name may not contain an equals sign or a comma. An attempt to access a queue that does not have a prefix of the client user name will result in a CORBA NO_PERMISSION system exception, unless access to the queue has been specifically granted to the client user.

    The config parameter may optionally specify:

    1. The name of a queue whose non-default configured properties will be used. If not specified, the system defaults will be used. The system defaults are: timeout=60, maximum=0, store=false, qop=none.
    2. The name of a thread pool (enclosed in brackets). The thread pool's reader and writer threads will be used for client notification. If not specified, this defaults to the system default client notification mechanism.

    The options parameter may include the following.

    OptionDescription REQUIRES_ACKNOWLEDGE Messages received from the queue must be explicitly acknowledged. REQUIRES_TRANSACTION Messages will be acknowledged in the caller's transaction, or in a new transaction if the caller has no transaction.

    Example: access a message queue "MyQueue" which will use non-default configuration properties from queue "PriceUpdates", and will use the reader and writer threads from "[ThreadPool]" for client notification.

    MessageQueue mq = cms.getMessageQueue("MyQueue", "PriceUpdates[ThreadPool]", 0);

  • getNames

    Get the names of entities of a particular type:

    CtsComponents::StringSeq getNames ( in long type );

    The available entity types are:

    ACTIVE_QUEUES ACTIVE_TOPICS CONFIGURED_QUEUES CONFIGURED_TOPICS THREAD_POOLS

  • getProperties

    Get the configuration properties of a named entity. See setProperties for details.

    CtsComponents::Properties getProperties ( in long type, in string name );

  • getRoles

    List the required roles for accessing name. See addRole.

    CtsComponents::StringSeq getRoles ( in long type, in string name );

    The type parameter is a bit mask composed of one of: MESSAGE_QUEUE, MESSAGE_TOPIC, and one of CONSUMER, PRODUCER, SECURITY.

  • getSelectors

    Return all of the selectors for a queue. See addSelector.

    CtsComponents::StringSeq getSelectors ( in string queue );

  • getStatistics

    Retrieve message service run-time statistics. For each key in keys, a corresponding value is returned in the result sequence.

    CtsComponents::DoubleSeq getStatistics ( in long type, in string name, in CtsComponents::ShortSeq keys );

    For type = MESSAGE_SERVICE (and name = ""), the following global counter keys are available:

    AVAILABLE_MESSAGES DELIVERED_MESSAGES DISCARDED_MESSAGES PUBLISHED_MESSAGES RECEIVE_CALLS PUBLISH_CALLS SEND_CALLS

    For type = MESSAGE_QUEUE (and queue name), the following queue counter keys are available:

    AVAILABLE_MESSAGES DELIVERED_MESSAGES DISCARDED_MESSAGES RECEIVE_CALLS SEND_CALLS

    For type = MESSAGE_TOPIC (and topic name), the following topic counter keys are available:

    PUBLISHED_MESSAGES PUBLISH_CALLS

    For type = THREAD_POOL (and thread pool name), the following thread pool keys are available:

    AVERAGE_READER_QUEUE_LENGTH AVERAGE_WRITER_QUEUE_LENGTH

  • getUniqueName

    Return a unique name that may be used for a temporary queue or topic. The type parameter is MESSAGE_QUEUE or MESSAGE_TOPIC.

    string getUniqueName ( in long type );

  • publish

    Publish a message with the specified message topic. A copy of this message will be sent to the queues for all consumers who have registered a message selector that returns TRUE when applied to this message.

    void publish ( in string topic, in CtsComponents::Message msg, in long options );

    The options parameter may include the following.

    OptionDescription PERSISTENT The message will be saved in persistent storage. REPLICATED The message will be replicated to all clustered servers. The message must be acknowledged by the recipient(s). If the message is not acknowledged by a recipient before it is deleted due to a message or queue timeout, a copy will be returned to the replyTo queue (if replyTo is provided) with the reply options including WAS_NOT_ACKNOWLEDGED.

    Note: all fields of msg are optional. If the message key is not provided, one will be generated by default. However if it is necessary to prevent the generation of duplicate messages in the event of a recoverable communications failure, the message key should be set using getMessageKey before publish is called.

    Example - notify registered clients of a new stock value:

    public void notifyStockValue(MessageService cms, String stock, double value) { String topic = "stock." + stock; String time = new java.util.Date().toString(); String text = time + ": The stock " + stock + " has value " + value; Message msg = new Message(); msg.key = cms.getMessageKey(); msg.props = new Property[2]; msg.props[0] = new Property("stock", new PropertyValue()); msg.props[0].value.stringValue(stock); msg.props[1] = new Property("value", new PropertyValue()); msg.props[1].value.doubleValue(value); msg.replyTo = ""; msg.text = text; cms.publish(topic, msg, 0); }

  • removeListener

    Remove a message listener from a queue. See addListener.

    void removeListener ( in string queue, in string listener );

  • removeRole

    Remove a required role for accessing name. See addRole.

    void removeRole ( in long type, in string name, in string role );

  • removeSelector

    Remove a message selector from a queue. See addSelector.

    void removeSelector ( in string queue, in string selector );

  • send

    Send a message to the specified message queue. If any listeners are registered for the queue, they will be notified asynchronously. Otherwise the message remains in the queue until it is received and acknowledged.

    void send ( in string queue, in CtsComponents::Message msg, in long options );

    The options parameter may include the following.

    OptionDescription PERSISTENT The message will be saved in persistent storage. REPLICATED The message will be replicated to all clustered servers. REQUIRES_ACKNOWLEDGE The message must be acknowledged by the recipient. If the message is not acknowledged by the recipient before it is deleted due to a message or queue timeout, a copy will be returned to the replyTo queue (if replyTo is provided) with the reply options including WAS_NOT_ACKNOWLEDGED. REQUIRES_TRANSACTION REQUIRES_TRANSACTION The message will be sent in the caller's transaction, or in a new transaction if the caller has no transaction.

    Note: all fields of msg are optional. If the message key is not provided, one will be generated by default. However if it is necessary to prevent the generation of duplicate messages in the event of a recoverable communications failure, the message key should be set using getMessageKey before send is called.

    Example - notify client of a completed order.

    public void notifyOrder(MessageService cms, String queue, int orderNo, String product) { String time = new java.util.Date().toString(); String text = "Order " + orderNo + " for product " + product + " was completed at " + time; Message msg = new Message(); msg.key = cms.getMessageKey(); msg.props = new Property[2]; msg.props[0] = new Property("orderNo", new PropertyValue()); msg.props[0].value.longValue(orderNo); msg.props[1] = new Property("product", new PropertyValue()); msg.props[1].value.stringValue(product); msg.replyTo = ""; msg.text = text; cms.send(queue, msg, PERSISTENT.value); }

  • setProperties

    Set the configuration properties of a named entity. If props is empty, all of the entity's properties will revert to their default values, and the entity is subsequently considered to be temporary (not configured). If props is not empty, only the specified properties are set or changed, and the entity is subsequently considered to be permanent (configured).

    void setProperties ( in long type, in string name, in CtsComponents::Properties props );

    The available entity types are:

    MESSAGE_SERVICE MESSAGE_QUEUE MESSAGE_TOPIC THREAD_POOL

    For type = MESSAGE_SERVICE, the available configuration properties are:

    PropertyTypeDefault ValueDescription debug boolean false Indicates whether message service debugging is enabled. This can be changed while the service is running.

    For type = MESSAGE_QUEUE, the available configuration properties are:

    PropertyTypeDefault ValueDescription maximum long 0 Indicates the maximum number of messages that can be held in the queue when it is active. Messages will be discarded from a queue in the order that they would be received in order to prevent the maximum being exceeded. A zero or negative value indicates no maximum queue length. timeout long 0 Indicates how many seconds the queue should remain in memory when it is not being actively accessed by a client, and it has no registered listeners. Any transient messages in memory when the timeout occurs will be discarded. Persistent messages will be discarded if the "store" property is false. A zero or negative size value indicates no timeout. A queue with no timeout will be automatically activated at server startup time. This is particularly useful for queues that have registered selectors or listeners that must always be active, and for queues that must store messages for a client even when the client is not active. store boolean false Indicates whether or not to retain persistent messages if the queue becomes inactive due to a timeout, and whether or not persistent messages will be stored in the queue while the queue is inactive. qop string "none" Indicates the quality of protection required for the message queue object.

    For type = MESSAGE_TOPIC, the available configuration properties are:

    PropertyTypeDefault ValueDescription timeout long 0 Indicates how many seconds the topic should remain in memory when it is not being actively accessed, i.e. no active queues have selectors registered for the topic. A zero or negative size value indicates no timeout. A topic with no timeout will be automatically activated at server startup time.

    For type = THREAD_POOL, the available configuration properties are:

    PropertyTypeDefault ValueDescription readers long 0 Indicates the number of worker threads in the thread pool. Reader threads are used for client notification. writers long 0 Indicates the number of worker threads in the thread pool. Writer threads are used for client notification. workers long 0 Indicates the number of worker threads in the thread pool. Worker threads are used for component notification.

Configuration

The following steps must be followed to configure the message service.

  1. With a text editor, edit the file $JAGUAR/Repository/Component/CtsComponents/MessageService.props.
    • Change the connection cache name in the line "cms.cache=MessageServiceCache" to the name of the connection cache you wish to use for storage of persistent message service data. The chosen connection cache must be a JDBC connection cache and must allow cache-by-name access.
    • Change the line "cms.force=false" to "cms.force=true" to enable the JCM_FORCE option for access to the database connection cache.
    • Change the line "cms.debug=false" to "cms.debug=true" if you wish to enable message service debugging.
    • Change the SQL commands in the XX.YYYYYY properties if your database server will not accept the default syntax. If the database does not have an "image" type, replace this with an unbounded (large) binary type. If the database driver has problems with character set conversion, change all the "varchar" columns in the SQL schemas to use "varbinary".
    • The required database tables will be created the first time the message service is started. These tables can be created manually beforehand if that is desirable. Check the XX.create properties for the SQL schemas.
  2. If using a cluster, copy the modified file to the other cluster members.
  3. Add "CtsComponents" to the "com.sybase.jaguar.server.packages" server property using the All Properties tab page in Jaguar Manager's Server Properties dialog.
  4. Add "CtsComponents/MessageService" to the "com.sybase.jaguar.server.services" server property, using the All Properties tab page in Jaguar Manager's Server Properties dialog.
  5. If using a cluster, synchronize the cluster.
  6. Restart the server(s).
Administration Tool

The administration tool for the message service is a Java applet built using the Swing GUI classes. It is designed to run in the JDK 1.2 Java browser-plug-in. Although it is primarily intended for administration, the tool provides GUI access to all of the methods of the message service API, including the sending, publishing, browsing and receiving of messages for testing purposes. The applet is packaged as a signed JAR file to allow once-only downloading by clients. It is also available in source code form, as a sample program.

For the Maui release, the administration tool will be integrated into Sybase Central, but the original administration tool will continue to be shipped as a sample.

High Availability

The message service uses server clustering to provide high availability. The failure of a single server in a cluster should not make messaging services unavailable. If a CORBA COMM_FAILURE system exception occurs while a client is accessing a message queue (calling acknowledge, list, or receive), a replacement message queue object can be obtained by calling getMessageQueue again. In that case, if the queue's previous options did not include REQUIRES_ACKNOWLEDGE, or if the queue's messages were not persistent, it is possible that some messages may have been irretrievably lost.

For maximum performance of client notification in high-throughput environments, it is better to design the client to recover from message loss than it is to use persistent messages with acknowledgement. For example, consider a client application which displays the "most recent price" for a selection of 50-100 products out of several thousand possible products, in an environment with frequent price changes. Assume that messages are used to notify clients of price changes. Upon receiving a CORBA COMM_FAILURE system exception, and assuming that some servers in the cluster are still available, the client could simply request the most recent price for each product, and then resume listening for price change messages after calling getMessageQueue again.

Load Balancing

The message service uses server clustering to provide automatic load balancing.

Message Security

The message service provides role-based security for queues and topics. There are three categories of access to a queue or topic.

  • CONSUMER access (addListener, getListeners, removeListener, addSelector, getSelectors, removeSelector, getMessageQueue, getStatistics)
  • PRODUCER access (publish, send)
  • SECURITY access (addRole, getRoles, removeRole)

Permissions for all three types of access must be assigned separately.

Queued Methods

Methods can be declared as 'queued'. A client-initiated IIOP invocation of a queued method will result in the unmarshalled IIOP request buffer being copied into a binary property of a message that is 'sent' to a queue. The listener for that queue will be an internal component that will process the message by invoking it as an IIOP request.

The name of the message queue for a queued method will be optionally user-configurable at the method level, the component level and the server level.

Reliable Delivery

The message service provides the following mechanisms for reliable message delivery:

  • IIOP connections (i.e. TCP/IP sockets) for client notification, so in most circumstances the only reason for failure to deliver a message is a server crash or network outage.
  • HTTP tunneling of the IIOP connection, so that messages can be delivered through client-side firewalls that accept only HTTP.
  • Component notification that is usually performed in-process, which reduces the chances of partial failure. Having the producer and consumer in one process means it is usually not necessary to deal with the issue that only one of them has failed.
  • Persistent message queues that allow a guarantee of message delivery so long as the persistent store does not fail.
Scalable Notification

The MessageQueue object is implemented with a specialized server IIOP handler that avoids the use of large numbers of waiting threads to handle blocking receive calls, and thereby avoids waking large numbers of threads for client notification.

Since clients also use operations of the MessageService interface, whose implementation is managed by an ordinary IIOP handler that assigns one thread per client connection, it is advisable for clients to use the IdleConnectionTimeout ORB initialization property so that a server can handle a large number of concurrent clients without allocating a large number of threads.

Transaction Management

The following operations can optionally be transactional. A transactional operation runs in the caller's transaction, or in a new transaction if the caller is not enlisted in a transaction.

  • send - a message producer can send a message within a transaction.
  • acknowledge - a client can acknowledge a received message within the same transaction as the processing of the message.
  • onMessage - a listener component with a transactional onMessage operation can process a message within the same transaction as the automatic acknowledgement which occurs after onMessage returns successfully.
Java Message Service

The Java Message Service (JMS) is a set of interfaces and associated semantics that define how a JMS client accesses the facilities of an enterprise messaging product. The message service has been designed so that it may be easily accessed via JMS interfaces.

The JMS provider consists of a set of classes in package com.sybase.jms that delegate to the message service through it's CORBA IDL interfaces.

JMS messages are mapped to IDL messages as follows:

JMS Message (interface)IDL Message (implementation) BytesMessage'body' property holds BINARY_VALUE MapMessage'.ABC' through ".XYZ" properties hold map values ObjectMessage'JavaObject' property holds serialized Java Object as BINARY_VALUE StreamMessage'.1' through '.N' properties hold stream values TextMessage'text' field holds text value

Generated by Jaguar CTS 3.5

Interface Repository Interface CtsComponents::MessageQueue

The message queue interface allows a client to list messages in a queue, receive messages from a queue, and acknowledge the receipt of messages.

A message queue is obtained by calling getMessageQueue.

Operation Index
  • acknowledge
  • close
  • list
  • receive
  • recover
Operations
  • acknowledge

    Acknowledge the receipt of a message, so it can be removed from the queue.

    void acknowledge ( in CtsComponents::MessageKey key );

    Note: if the queue's options do not include REQUIRES_ACKNOWLEDGE, then messages need not be explicitly acknowledged.

  • close

    Close this message queue object. If there is a blocking receive call in progress for this queue, it will return immediately with a CORBA OBJECT_NOT_EXIST system exception.

    void close ( );

    A client performing a graceful shutdown should use this operation to allow the server to release resources immediately rather than waiting for the queue to timeout.

  • list

    Return a copy of at most maximum messages in queue after the message with key lastKey that match the specified selector expression (use "TRUE" to match all messages). If after is an empty key, the returned list starts from the first message in the queue. If maximum is zero or negative, all available messages will be returned at once.

    CtsComponents::MessageSeq list ( in string selector, in CtsComponents::MessageKey after, in long maximum );

    Note: the returned messages are not acknowledged, so they remain in the queue.

    Example: list all messages in the queue 100 at a time.

    MessageKey after = new MessageKey(new byte[0]); for (;;) { Message[] seq = mq.list("TRUE", after, 100); if (seq.length == 0) { break; } for (int m = 0; m < seq.length; m++) { Message msg = seq[m]; print(msg); after = msg.key; } }

  • receive

    Receive up to maximum messages (or all messages if maximum is zero or negative) from the queue. If any messages are already available in the queue, or if no messages are available and timeout is zero or negative, return immediately, otherwise wait up to timeout seconds for new messages to arrive.

    CtsComponents::MessageSeq receive ( in long maximum, in long timeout );

    For optimal use of the network, it is recommended to set maximum to zero, or otherwise as large as the client can manage.

    Although polling (timeout = 0) is permitted, it usually results in excessive network traffic, so a non-zero timeout is recommended. The main purpose of the timeout parameter is to allow the server to detect disconnected clients with inactive queues, and thereby release the resources associated with client connections. Unless the client requires a particular timeout value, it is recommended to use the DEFAULT_TIMEOUT value. Since the client thread calling receive will block until receive returns, it is recommended that a separate client thread be used to receive messages.

    Example: a client application that receives messages from a queue. This example uses a Java thread and a client-side listener object for message notification.

    import org.omg.CORBA.*; import CtsComponents.*; import java.lang.Object; import SessionManager.*; public class MessageClient implements MessageListenerOperations { private static String _url = "iiop://localhost:9000"; private static String _user = "testuser"; private static String _password = "testpass"; private static String _queue = _user + ":OrderQueue"; public static void main(String[] args) throws Exception { new MessageClient().run(args); } private void run(String[] args) throws Exception { java.util.Properties props = new java.util.Properties(); props.put("org.omg.CORBA.ORBClass", "com.sybase.CORBA.ORB"); props.put("com.sybase.CORBA.IdleConnectionTimeout", "60"); ORB orb = ORB.init(args, props); Manager manager = ManagerHelper.narrow(orb.string_to_object(_url)); Session session = manager.createSession(_user, _password); Factory factory = FactoryHelper.narrow(session.lookup("CtsComponents/MessageService")); MessageService cms = MessageServiceHelper.narrow(factory.create()); new MessageThread(cms, _queue, this).start(); for (;;) { // Do something while MessageThread asynchronously notifies // us of completed orders. System.out.println("sleeping..."); Thread.sleep(60000); // 1 minute } } public void onMessage(Message msg) { System.out.println("Received message: " + msg.text); } class MessageThread extends Thread { private MessageService _cms; private String _queue; private MessageListenerOperations _listener; MessageThread (MessageService cms, String queue, MessageListenerOperations listener) { _cms = cms; _queue = queue; _listener = listener; } public void run() { MessageQueue mq = _cms.getMessageQueue(_queue, "", REQUIRES_ACKNOWLEDGE.value); for (;;) { Message[] seq = mq.receive(0, DEFAULT_TIMEOUT.value); for (int m = 0; m < seq.length; m++) { Message msg = seq[m]; _listener.onMessage(msg); mq.acknowledge(msg.key); } } } } }

  • recover

    Recover messages that have been received but not acknowledged so they can be received again. This is only useful when using explicit acknowledgement.

    void recover ( );

Generated by Jaguar CTS 3.5

Interface Repository Interface CtsComponents::ThreadManager

The thread manager supports the dynamic creation and management of component-based threads. A component-based thread is a thread that executes an object (component instance) that has a 'run' method with no parameters and no results.

Operation Index
  • getRunInterval
  • getThreadCount
  • resume
  • setRunInterval
  • setThreadCount
  • start
  • stop
  • suspend
Operations
  • getRunInterval

    Get the current run interval for a thread group. The value -1 indicates no run interval, otherwise the run interval is zero or positive.

    long getRunInterval ( in string group );

  • getThreadCount

    Get the current number of active threads for the thread group. This operation is only useful for thread groups with a zero or positive run interval.

    long getThreadCount ( in string group, in boolean running );

  • resume

    Resume all suspended threads in the thread group. This operation is only useful for thread groups with a zero or positive run interval.

    void resume ( in string group );

  • setRunInterval

    Set the current run interval for a thread group. The value -1 indicates no run interval, otherwise the run interval is zero or positive.

    void setRunInterval ( in string group, in long seconds );

  • setThreadCount

    Ensure that no more than the specified number of threads are active for the thread group. This operation is only useful for thread groups with a zero or positive run interval.

    void setThreadCount ( in string group, in long threads );

    Note: the stop() call is equivalent to setThreadCount(0).

  • start

    Start a new thread which executes the 'run' method on the 'thread' object. If the run interval for the thread group is zero or positive, it specifies a wait time between repeated calls to 'run'. If the run interval is -1 (the default), it specifies that the 'run' method should be called only once.

    void start ( in string group, in Object thread );

    Note: the 'thread' object can be for any component, including pre-initialized stateful components and entity components. This is useful if it is required to initialize the state of the 'thread' object before starting it in a new thread.

  • stop

    Stop all threads in the thread group. Each of the active threads in the thread group will stop the next time they return from 'run'. This operation is only useful for thread groups with a zero or positive run interval.

    void stop ( in string group );

  • suspend

    Suspend all threads in the thread group. Each of the active threads in the thread group will be suspended the next time they return from 'run'. This operation is only useful for thread groups with a zero or positive run interval.

    void suspend ( in string group );

Generated by Jaguar CTS 3.5