Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Connection |
|
| 1.0;1 |
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 | } |