The Queue data type enables you to establish a connection to a message queue and allows you to send and receive messages to and from the queue. This data type will therefore make it possible to develop applications that require interaction with other applications that are not connected, with all the advantages of this type of programming, such as asynchronic communication and processing.
The Queue data type will allow you to establish a connection to a message queue. Once this connection is established, you will be able to send and receive messages to and from the queue. The messages sent are defined by the QueueMessage data type, which consists of a text and a priority (see QueueMessage data type).
The Queue data type enables you to establish a connection to the two types of existing queues:
- Point to point: a message is sent to the queue and then a client consumes the message (which then no longer exists in the queue). This means that once a message has been sent, a client can then connect to the queue and retrieve the message (if it hasn't been consumed yet).
- Publish / Subscribe: a message is sent to the queue and only the clients that are already connected to the queue will be able to receive the message. If a client connects to the queue after the message has been sent, this client won't receive the message.
| Provider |
Indicates the provider of the queue to be used, defined in the jms.xml file. |
| User |
Overwrites the user setup in the provider. |
| Password |
Overwrites the password setup in the provider. |
| Browse |
Indicates whether the messages will be kept in the queue or if they will be removed from it. |
| errCode |
Indicates the error code in case an error happened when a method was executed, returns 0 otherwise |
| errDescription |
Indicates the error detail in case an error happened |
Provider
Indicates who the provider of the queue to be used is. The name of the provider must have previously been defined in the jms.xml file (see Defining providers). This file must be located in the application directory (DATANNN).
User
Overwrites the user setup in the provider.
&queue.user = "myUser"
Password
Overwrites the password setup in the provider.
&queue.password = "myPassword"
Browse
Indicates whether the messages will be kept in the queue or if they will be removed from it.
The default value is False.
&queue.browse = True
errCode
Read only property, Indicates the error code in case an error happened when a method was executed, returns 0 otherwise
Default value 0
&errcode = &queue.errCode
errDescription
Read only property, Indicates the error detail in case an error happened
&errDsc = &queue.errDescription
| Connect |
Establishes a connection with the queue defined in Provider. |
| Disconnect |
Ends the connection with the queue. |
| Send |
Sends a message to the queue. |
| Commit |
Commits all the messages that haven't been commited. |
| Rollback |
Rollbacks all the messages that haven't been commited. |
<Boolean> = Connect()
Establishes a connection with the queue defined in provider. It returns True if the connection was possible and False if it was not possible.
&Boolean = &queue.connect()
Disconnect
Ends the connection with the queue.
&queue.disconnect()
<String> = Send(QueueMessage message)
Sends a message to the queue. If the message was sent successfully, it returns its ID; otherwise it returns "".
&char = &queue.send(&queueMessage)
Commit
Sends all the messages that weren't commited to the queue (if Queue_AutoCommit = NO. See "Defining Providers").
Rollback
Rollbacks all the messages that haven't been sent to the queue (if Queue_AutoCommit = NO. See "Defining Providers").
To process the messages you must use the "For in" command as follows:
For &message in &queue
... //Work with &message
EndFor
Defining Providers in Java
To define a provider it is necessary to create a jms.xml file under the application directory. This file will contain information on different providers. The following is a complete example of a jms.xml file.
<JMS_Providers>
<Provider>
<Name>queueProvider</Name>
<User></User>
<Password></Password>
<Type>Queue</Type>
<Factory>com.sun.enterprise.naming.SerialInitContextFactory</Factory>
<URL>iiop://myserver:1050</URL>
<JNDI_ID>QueueConnectionFactory</JNDI_ID>
<Queue_Name>Queue</Queue_Name>
<Queue_AutoCommit>YES</Queue_AutoCommit>
</Provider>
<Provider>
....
</Provider>
</JMS_Providers>
| <Name> |
Provider's name. This name will then be used in GeneXus when connecting to the queue (&queue.Provider = queueProvider). |
| <User> |
The user's identification. |
| <Password> |
Password of the user specified at <User> |
| <Type> |
The type can be either a Queue or a Topic depending on the destination defined in the server. |
| <Factory> |
This is the initial context factory class, which is different for every server. For J2EE application servers, it's: com.sun.enterprise.naming.SerialInitContextFactory. For OpenJMS servers, it's: org.exolab.jms.jndi.InitialContextFactory. |
| <URL> |
The URL of the server. |
| <JNDI_ID> |
Name of the connection factory previously defined in the server. |
| <Queue_Name> |
Name of the queue (the destination previously defined in the server). |
| <Queue_AutoCommit> |
Indicates if the messages will have to be commited or not. If "NO" is specified, messages will be stored in memory and it will be necessary to make &queue.commit() in order to send them. If "YES" is specified, there is no need to make &queue.commit() because they will be automatically sent every time the &queue.Send() method is invoked. |
For further information, see "Creating queues with J2EE Software Development Kit (SDK) version 1.3.1".
Defining Providers in .NET
In .NET the provider must be defined in the client.exe.config file for command line programs or web.config file of the web application. Under AppSetting, you need to add:
<add key="<Queue-ProviderName>" value="<server>\<queue>"/>
Where ProviderName is the name that is going to be set to &queue.provider property, <server> is the name of the server and <queue> is the name of the queue defined in the server. When defining the queue, take into account that you must include the prefix "Queue" in the definition, but that the prefix is not used from GeneXus (only the ProviderName is used): For example:
In client.exe.config:
<add key="Queue-MyFirstQueue" value="paul-xp\myQueue"/>
Then from GX you must use:
&queue.provider = "MyFirstQueue"
In order to define a message queue in .NET you must have previously installed the Messsage Queuing service. After that you will be able to create a Queue. Note that when creating the queue, you can either set it as a transactional queue or not. If transactional is set to NO, the commit and rollback methods of the message queue data type will be disabled and messages will automatically be sent in the "Send" method (so it won't be necessary to commit the messages).
Objects: Procedures, Transactions, Web Panels
Languages: Java, .NET, Ruby (up to GeneXus X Evolution 3)
Interfaces: Web