All Downloads are FREE. Search and download functionalities are using the official Maven repository.

nats.client.Nats Maven / Gradle / Ivy

There is a newer version: 0.5.Beta4
Show newest version
/*
 *   Copyright (c) 2012 Mike Heath.  All rights reserved.
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 *
 */
package nats.client;

import java.io.Closeable;

/**
 * Provides the interface for publishing messages and subscribing to NATS subjects. This class is responsible for
 * maintaining a connection to the NATS server as well as automatic fail-over to a second server if the
 * connection to one server fails.
 * 

*

This class is fully thread-safe. * * @author Mike Heath */ public interface Nats extends Closeable { /** * Indicates if this client is connected to a NATS server. This method will always return {@code false} after the * {@link #close()} method has been invoked. If the connection to the server is lost, the client will automatically * try to reconnect to a server unless, of course, this feature has been disabled. * * @return {@code true} if the client is connected to a NATS server, {@code false} otherwise. */ boolean isConnected(); /** * Indicates if this client has been closed. * * @return {@code true} if {@link #close()} was called (explicitly or implicitly due to an error), {@code false} * otherwise. */ boolean isClosed(); /** * Closes this Nats instance. Closes the connection to the Nats server, closes any subscriptions, cancels any * pending messages to be published. */ void close(); /** * Publishes an empty body to the specified subject. If this {@code Nats} instance is not currently connected to * a Nats server, the body will be queued up to be published once a connection is established. * * @param subject the subject to publish to */ void publish(String subject); /** * Publishes a body to the specified subject. If this {@code Nats} instance is not currently connected to a Nats * server, the body will be queued up to be published once a connection is established. * * @param subject the subject to publish to * @param body the body to publish */ void publish(String subject, String body); /** * Publishes a body to the specified subject. If this {@code Nats} instance is not currently connected to a Nats * server, the body will be queued up to be published once a connection is established. * * @param subject the subject to publish to * @param body the body to publish * @param replyTo the subject replies to this body should be sent to. */ void publish(String subject, String body, String replyTo); /** * Subscribes to the specified subject. * * @param subject the subject to subscribe to. * @return a {@code Subscription} object used for interacting with the subscription * @see #subscribe(String, String, Integer,MessageHandler...) */ Subscription subscribe(String subject, MessageHandler... messageHandlers); /** * Subscribes to the specified subject within a specific queue group. The subject can be a specific subject or * include wild cards. A body to a particular subject will be delivered to only member of the same queue group. * * @param subject the subject to subscribe to * @param queueGroup the queue group the subscription participates in * @return a {@code Subscription} object used for interacting with the subscription * @see #subscribe(String, String, Integer,MessageHandler...) */ Subscription subscribe(String subject, String queueGroup, MessageHandler... messageHandlers); /** * Subscribes to the specified subject and will automatically unsubscribe after the specified number of messages * arrives. * * @param subject the subject to subscribe to * @param messageHandlers the {@code MessageHandler}s to listen for incoming messages. * @return a {@code Subscription} object used for interacting with the subscription * @see #subscribe(String, String, Integer,MessageHandler...) */ Subscription subscribe(String subject, Integer maxMessages, MessageHandler... messageHandlers); /** * Subscribes to the specified subject within a specific queue group and will automatically unsubscribe after the * specified number of messages arrives. *

*

The {@code subject} may contain wild cards. "*" matches any token, at any level of the subject. For example: *

	 *     "foo.*.baz"  matches "foo.bar.baz, foo.a.baz, etc.
	 *     "*.bar" matches "foo.bar", "baz.bar", etc.
	 *     "*.bar.*" matches "foo.bar.baz", "foo.bar.foo", etc.
	 * 
*

*

">" matches any length of the tail of a subject and can only be the last token. For examples, 'foo.>' will * match 'foo.bar', 'foo.bar.baz', 'foo.foo.bar.bax.22'. A subject of simply ">" will match all messages. *

*

All subscriptions with the same {@code queueGroup} will form a queue group. Each body will be delivered to * only one subscriber per queue group. * * @param subject the subject to subscribe to * @param queueGroup the queue group the subscription participates in * @param messageHandlers the {@code MessageHandler}s to listen for incoming messages. * @return a {@code Subscription} object used for interacting with the subscription */ Subscription subscribe(String subject, String queueGroup, Integer maxMessages, MessageHandler... messageHandlers); /** * Sends a request body on the given subject. Request responses can be handled using the returned * {@link Request}. * * @param subject the subject to send the request on * @param message the content of the request * @param messageHandlers the {@code MessageHandler}s to listen for incoming messages. * @return a {@code Request} instance associated with the request. * @see #request(String, String, Integer, MessageHandler...) */ Request request(String subject, String message, MessageHandler... messageHandlers); /** * Sends a request on the given subject with an empty body. Request responses can be handled using the returned * {@link Request}. * * @param subject the subject to send the request on * @param messageHandlers the {@code MessageHandler}s to listen for incoming messages. * @return a {@code Request} instance associated with the request. * @see #request(String, String, Integer, MessageHandler...) */ Request request(String subject, MessageHandler... messageHandlers); /** * Sends a request body on the given subject. Request responses can be handled using the returned * {@link Request}. *

* Invoking this method is roughly equivalent to the following: *

* * String replyTo = Nats.createInbox(); * Subscription subscription = nats.subscribe(replyTo, maxReplies); * Publication publication = nats.publish(subject, body, replyTo); * *

* that returns a combination of {@code Subscription} and {@code Publication} as a {@code Request} object. * * @param subject the subject to send the request on * @param message the content of the request * @param maxReplies the maximum number of replies that the request will accept before automatically closing, * {@code null} for unlimited replies * @param messageHandlers the {@code MessageHandler}s to listen for incoming messages. * @return a {@code Request} instance associated with the request. */ Request request(String subject, String message, Integer maxReplies, MessageHandler... messageHandlers); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy