1 /*
2 * #%L
3 * Connection.java - mongodb-async-driver - Allanbank Consulting, Inc.
4 * %%
5 * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
6 * %%
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * #L%
19 */
20 package com.allanbank.mongodb.client.connection;
21
22 import java.beans.PropertyChangeListener;
23 import java.io.Closeable;
24 import java.io.Flushable;
25 import java.util.concurrent.TimeUnit;
26
27 import com.allanbank.mongodb.MongoDbException;
28 import com.allanbank.mongodb.client.Message;
29 import com.allanbank.mongodb.client.callback.ReplyCallback;
30
31 /**
32 * Provides the lowest level interface for interacting with a MongoDB server.
33 * The method provided here are a straight forward mapping from the <a href=
34 * "http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol">MongoDB Wire
35 * Protocol</a>.
36 *
37 * @api.no This class is <b>NOT</b> part of the drivers API. This class may be
38 * mutated in incompatible ways between any two releases of the driver.
39 * @copyright 2011-2014, Allanbank Consulting, Inc., All Rights Reserved
40 */
41 public interface Connection extends Closeable, Flushable {
42
43 /** The collection to use when issuing commands to the database. */
44 public static final String COMMAND_COLLECTION = "$cmd";
45
46 /** The property for if the connection is open or not. */
47 public static final String OPEN_PROP_NAME = "open";
48
49 /**
50 * Adds a {@link PropertyChangeListener} to this connection. Events are
51 * fired as the state of the connection changes.
52 *
53 * @param listener
54 * The listener for the change events.
55 */
56 public void addPropertyChangeListener(PropertyChangeListener listener);
57
58 /**
59 * Returns the number of messages that are pending responses from the
60 * server.
61 *
62 * @return The number of messages pending responses from the server.
63 */
64 public int getPendingCount();
65
66 /**
67 * Returns the name of a server the connection is currently connected to.
68 *
69 * @return The name of a server the connection is currently connected to.
70 */
71 public String getServerName();
72
73 /**
74 * Returns true if the connection is open and not shutting down, false
75 * otherwise.
76 *
77 * @return True if the connection is open and not shutting down, false
78 * otherwise.
79 */
80 public boolean isAvailable();
81
82 /**
83 * Determines if the connection is idle.
84 *
85 * @return True if the connection is waiting for messages to send and has no
86 * outstanding messages to receive.
87 */
88 public boolean isIdle();
89
90 /**
91 * Determines if the connection is open.
92 *
93 * @return True if the connection is open and thinks it can send messages.
94 */
95 public boolean isOpen();
96
97 /**
98 * Returns true if the connection is being gracefully closed, false
99 * otherwise.
100 *
101 * @return True if the connection is being gracefully closed, false
102 * otherwise.
103 */
104 public boolean isShuttingDown();
105
106 /**
107 * Notifies the call backs for the pending and optionally the to be sent
108 * messages that there has been an external, unrecoverable error.
109 *
110 * @param exception
111 * The error condition.
112 */
113 public void raiseErrors(MongoDbException exception);
114
115 /**
116 * Removes a {@link PropertyChangeListener} from this connection.
117 *
118 * @param listener
119 * The listener for the change events.
120 */
121 public void removePropertyChangeListener(PropertyChangeListener listener);
122
123 /**
124 * Sends a message on the connection.
125 *
126 * @param message1
127 * The first message to send on the connection.
128 * @param message2
129 * The second message to send on the connection.
130 * @param replyCallback
131 * The callback to notify of responses to the {@code message2}.
132 * May be <code>null</code>.
133 * @throws MongoDbException
134 * On an error sending the message.
135 */
136 public void send(Message message1, Message message2,
137 ReplyCallback replyCallback) throws MongoDbException;
138
139 /**
140 * Sends a message on the connection.
141 *
142 * @param message
143 * The message to send on the connection.
144 * @param replyCallback
145 * The callback to notify of responses to the messages. May be
146 * <code>null</code>.
147 * @throws MongoDbException
148 * On an error sending the message.
149 */
150 public void send(Message message, ReplyCallback replyCallback)
151 throws MongoDbException;
152
153 /**
154 * Notifies the connection that once all outstanding requests have been sent
155 * and all replies received the Connection should be closed. This method
156 * will return prior to the connection being closed.
157 *
158 * @param force
159 * If true then the connection can be immediately closed as the
160 * caller knows there are no outstanding requests to the server.
161 */
162 public void shutdown(boolean force);
163
164 /**
165 * Waits for the connection to become idle.
166 *
167 * @param timeout
168 * The amount of time to wait for the connection to become idle.
169 * @param timeoutUnits
170 * The units for the amount of time to wait for the connection to
171 * become idle.
172 */
173 public void waitForClosed(int timeout, TimeUnit timeoutUnits);
174 }