Merge pull request #112 from ayeshLK/api-docs

Update API docs

ballerina/caller.bal

@@ -16,7 +16,7 @@
 
 import ballerina/jballerina.java;
 
-# Represents a JMS caller, which can be used to commit the offsets consumed by the service.
+# Represents a JMS caller, which can be used to mark JMS message as received.
 public isolated client class Caller {
 
  # Mark a JMS message as received.

ballerina/connection.bal

@@ -21,6 +21,12 @@ public isolated client class Connection {
  private final readonly & ConnectionConfiguration config;
 
  # Initialize and starts a JMS connection.
+ # ```ballerina
+ # jms:Connection connection = check new (
+ # initialContextFactory = "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
+ # providerUrl = "tcp://localhost:61616"
+ # );
+ # ```
  #
  # + connectionConfig - The configurations to be used when initializing the JMS connection
  # + return - The `jms:Connection` or an `jms:Error` if the initialization failed
@@ -35,6 +41,9 @@ public isolated client class Connection {
  } external;
 
  # Create a Session object, specifying transacted and acknowledgeMode.
+ # ```ballerina
+ # jms:Session session = check connection->createSession();
+ # ```
  #
  # + ackMode - Configuration indicating how messages received by the session will be acknowledged
  # + return - Returns the Session or an error if it fails.
@@ -44,6 +53,9 @@ public isolated client class Connection {
 
  # Starts (or restarts) a connection's delivery of incoming messages.
  # A call to start on a connection that has already been started is ignored.
+ # ```ballerina
+ # check connection->'start();
+ # ```
  #
  # + return - A `jms:Error` if threre is an error while starting the connection
  isolated remote function 'start() returns Error? = @java:Method {
@@ -53,13 +65,19 @@ public isolated client class Connection {
 
  # Temporarily stops a connection's delivery of incoming messages.
  # Delivery can be restarted using the connection's start method.
+ # ```ballerina
+ # check connection->stop();
+ # ```
  #
  # + return - A `jms:Error` if threre is an error while stopping the connection
  isolated remote function stop() returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.JmsConnection"
  } external;
 
  # Closes the connection.
+ # ```ballerina
+ # check connection->close();
+ # ```
  #
  # + return - A `jms:Error` if threre is an error while closing the connection
  isolated remote function close() returns Error? = @java:Method {

ballerina/message_consumer.bal

@@ -74,31 +74,45 @@ public isolated client class MessageConsumer {
  } external;
 
  # Receives the next message that arrives within the specified timeout interval.
+ # ```ballerina
+ # jms:Message? message = check consumer->receive(10000);
+ # ```
  #
  # + timeoutMillis - Message receive timeout
- # + return - `jms:JmsMessage` or `jsm:Error` if there is an error in the execution
- isolated remote function receive(int timeoutMillis = 0) returns Message|Error? = @java:Method {
+ # + return - A `jms:JmsMessage` if there is a new message, `()` if there is no any new message, 
+ # or else a `jsm:Error` if there is an error in the execution
+ isolated remote function receive(int timeoutMillis = 10000) returns Message|Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.consumer.Actions"
  } external;
 
  # Receives the next message if one is immediately available.
- #
- # + return - `jms:JmsMessage` or `jsm:Error` if there is an error in the execution
+ # ```ballerina
+ # jms:Message? message = check consumer->receiveNoWait();
+ # ```
+ # 
+ # + return - A `jms:JmsMessage` if there is a new message, `()` if there is no any new message, 
+ # or else a `jsm:Error` if there is an error in the execution
  isolated remote function receiveNoWait() returns Message|Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.consumer.Actions"
  } external;
 
  # Mark a JMS message as received.
+ # ```ballerina
+ # check consumer->acknowledge(message);
+ # ```
  #
  # + message - JMS message record
- # + return - `jms:Error` if there is an error in the execution or else nil
+ # + return - A `jms:Error` if there is an error in the execution or else `()`
  isolated remote function acknowledge(Message message) returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.consumer.Actions"
  } external;
 
  # Closes the message consumer.
+ # ```ballerina
+ # check consumer->close();
+ # ```
  #
- # + return - `jms:Error` if there is an error or else nil
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function close() returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.consumer.Actions"
  } external;

ballerina/message_listener.bal

@@ -37,57 +37,75 @@ public isolated class Listener {
  private final MessageConsumer consumer;
 
  # Creates a new `jms:Listener`.
- #
- # + consumer - The relevant JMS consumer.
- public isolated function init(*MessageListenerConfigurations consumerConfig) returns error? {
- Connection connection = check new (consumerConfig.connectionConfig);
- Session session = check connection->createSession(consumerConfig.acknowledgementMode);
- self.consumer = check new(session, consumerConfig.consumerOptions);
+ # ```ballerina
+ # listener jms:Listener messageListener = check new(
+ # connectionConfig = {
+ # initialContextFactory: "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
+ # providerUrl: "tcp://localhost:61616"
+ # },
+ # consumerOptions = {
+ # destination: {
+ # 'type: jms:QUEUE,
+ # name: "test-queue"
+ # }
+ # }
+ # );
+ # ```
+ # 
+ # + listenerConfig - Message listener configurations
+ # + return - The relevant JMS consumer or a `jms:Error` if there is any error
+ public isolated function init(*MessageListenerConfigurations listenerConfig) returns Error? {
+ Connection connection = check new (listenerConfig.connectionConfig);
+ Session session = check connection->createSession(listenerConfig.acknowledgementMode);
+ self.consumer = check new(session, listenerConfig.consumerOptions);
  }
 
  # Attaches a message consumer service to a listener.
  # ```ballerina
- # error? result = listener.attach(jmsService);
+ # check messageListener.attach(jmsService);
  # ```
  # 
- # + 'service - The service instance.
- # + name - Name of the service.
- # + return - Returns nil or an error upon failure to register the listener.
+ # + 'service - The service instance
+ # + name - Name of the service
+ # + return - A `jms:Error` if there is an error or else `()`
  public isolated function attach(Service 'service, string[]|string? name = ()) returns Error? {
  return setMessageListener(self.consumer, 'service);
  }
 
  # Detaches a message consumer service from the the listener.
  # ```ballerina
- # error? result = listener.detach(jmsService);
+ # check messageListener.detach(jmsService);
  # ```
  #
  # + 'service - The service to be detached
- # + return - A `jms:Error` if an error is encountered while detaching a service or else `()`
+ # + return - A `jms:Error` if there is an error or else `()`
  public isolated function detach(Service 'service) returns Error? {}
 
  # Starts the endpoint.
+ # ```ballerina
+ # check messageListener.'start();
+ # ```
  #
- # + return - Returns nil or an error upon failure to start.
+ # + return - A `jms:Error` if there is an error or else `()`
  public isolated function 'start() returns Error? {}
 
 
  # Stops the JMS listener gracefully.
  # ```ballerina
- # error? result = listener.gracefulStop();
+ # check messageListener.gracefulStop();
  # ```
  #
- # + return - A `jms:JmsError` if an error is encountered during the listener-stopping process or else `()`
+ # + return - A `jms:Error` if there is an error or else `()`
  public isolated function gracefulStop() returns Error? {
  return self.consumer->close();
  }
 
  # Stops the JMS listener immediately.
  # ```ballerina
- # error? result = listener.immediateStop();
+ # check messageListener.immediateStop();
  # ```
  #
- # + return - A `jms:JmsError` if an error is encountered during the listener-stopping process or else `()`
+ # + return - A `jms:Error` if there is an error or else `()`
  public isolated function immediateStop() returns Error? {
  return self.consumer->close();
  }

ballerina/message_producer.bal

@@ -31,9 +31,12 @@ public isolated client class MessageProducer {
  } external;
 
  # Sends a message to the JMS provider.
+ # ```ballerina
+ # check producer->send(message);
+ # ```
  #
  # + message - Message to be sent to the JMS provider
- # + return - Error if unable to send the message to the queue
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function send(Message message) returns Error? {
  handle jmsMessage = check getJmsMessage(self.session, message);
  return self.externSend(jmsMessage);
@@ -45,10 +48,13 @@ public isolated client class MessageProducer {
  } external;
 
  # Sends a message to a given destination of the JMS provider.
+ # ```ballerina
+ # check producer->sendTo({ 'type: QUEUE, name: "test-queue" }, message);
+ # ```
  #
  # + destination - Destination used for the message sender
  # + message - Message to be sent to the JMS provider
- # + return - Error if sending to the given destination fails
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function sendTo(Destination destination, Message message) returns Error? {
  handle jmsMessage = check getJmsMessage(self.session, message);
  return self.externSendTo(self.session, destination, jmsMessage);
@@ -61,8 +67,10 @@ public isolated client class MessageProducer {
  } external;
 
  # Closes the message producer.
- # 
- # + return - `jms:Error` if there is an error or else nil
+ # ```ballerina
+ # check producer->close();
+ # ```
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function close() returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.producer.Actions"
  } external;

ballerina/session.bal

@@ -28,50 +28,74 @@ public isolated client class Session {
  'class: "io.ballerina.stdlib.java.jms.JmsSession"
  } external;
 
- # Unsubscribe a durable subscription that has been created by a client.
+ # Unsubscribe a durable subscription that has been created by this session.
  # It is erroneous for a client to delete a durable subscription while there is an active (not closed) consumer
  # for the subscription, or while a consumed message being part of a pending transaction or has not been
  # acknowledged in the session.
+ # ```ballerina
+ # check session->unsubscribe("subscription-1");
+ # ```
  #
- # + subscriptionId - The name, which is used to identify the subscription.
- # + return - Cancels the subscription.
+ # + subscriptionId - The name, which is used to identify the subscription
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function unsubscribe(string subscriptionId) returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.JmsSession"
  } external;
 
  # Creates a MessageProducer to send messages to the specified destination.
+ # ```ballerina
+ # jms:MessageProducer producer = check session.createProducer({
+ # 'type: jms:QUEUE,
+ # name: "test-queue"
+ # });
+ # ```
  #
  # + destination - The Destination to send to, or nil if this is a producer which does not have a specified destination
- # + return - Returns jms:MessageProducer
+ # + return - Returns `jms:MessageProducer` or `jms:Error` if there is an error
  public isolated function createProducer(Destination? destination = ()) returns MessageProducer|Error {
  return new MessageProducer(self, destination);
  }
 
  # Creates a MessageConsumer for the specified destination.
+ # ```ballerina
+ # jms:MessageConsumer consumer = check session.createConsumer(destination = {
+ # 'type: jms:QUEUE,
+ # name: "test-queue"
+ # });
+ # ```
  #
  # + consumerOptions - The relevant consumer configurations
- # + return - Returns a jms:MessageConsumer
+ # + return - Returns a `jms:MessageConsumer` or else `jms:Error` if there is an error
  public isolated function createConsumer(*ConsumerOptions consumerOptions) returns MessageConsumer|Error {
  return new MessageConsumer(self, consumerOptions);
  }
 
- # Commits all messages done in this transaction and releases any locks currently held.
+ # Commits all messages sent/received in this transaction and releases any locks currently held.
+ # ```ballerina
+ # check session->'commit();
+ # ```
  # 
- # + return - `jms:Error` if there is an error or else nil
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function 'commit() returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.JmsSession"
  } external;
 
- # Rolls back any messages done in this transaction and releases any locks currently held.
+ # Rolls back any messages sent/received in this transaction and releases any locks currently held.
+ # ```ballerina
+ # check session->'rollback();
+ # ```
  # 
- # + return - `jms:Error` if there is an error or else nil
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function 'rollback() returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.JmsSession"
  } external;
 
- # Closes the session.
+ # Closes the current JMS session.
+ # ```ballerina
+ # check session->close();
+ # ```
  # 
- # + return - `jms:Error` if there is an error or else nil
+ # + return - A `jms:Error` if there is an error or else `()`
  isolated remote function close() returns Error? = @java:Method {
  'class: "io.ballerina.stdlib.java.jms.JmsSession"
  } external;