1 /*
2 * #%L
3 * Message.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;
21
22 import java.io.IOException;
23
24 import com.allanbank.mongodb.ReadPreference;
25 import com.allanbank.mongodb.bson.io.BsonOutputStream;
26 import com.allanbank.mongodb.bson.io.BufferingBsonOutputStream;
27 import com.allanbank.mongodb.error.DocumentToLargeException;
28
29 /**
30 * Common interface for all MongoDB messages read from and sent to a MongoDB
31 * server.
32 *
33 * @api.no This class is <b>NOT</b> part of the drivers API. This class may be
34 * mutated in incompatible ways between any two releases of the driver.
35 * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
36 */
37 public interface Message {
38
39 /**
40 * Returns the name of the database.
41 *
42 * @return The name of the database.
43 */
44 public String getDatabaseName();
45
46 /**
47 * Returns a short name for the operation.
48 *
49 * @return A short name for the operation.
50 */
51 public String getOperationName();
52
53 /**
54 * Provides the details on which servers are eligible to receive the
55 * message.
56 *
57 * @return The {@link ReadPreference} for which servers should be sent the
58 * request.
59 */
60 public ReadPreference getReadPreference();
61
62 /**
63 * Returns the required version range for the message.
64 * <p>
65 * This may be {@code null} which should be interpreted to mean that all
66 * versions of the server support the message's operation. In reality that
67 * is probably more accurately stated as all supported versions.
68 * </p>
69 *
70 * @return The version of the server that introduced support for the
71 * operation.
72 */
73 public VersionRange getRequiredVersionRange();
74
75 /**
76 * Returns the total size of the message on the wire.
77 *
78 * @return The size of the message on the wire.
79 */
80 public int size();
81
82 /**
83 * Validates that the documents with the message do not exceed the maximum
84 * document size specified.
85 *
86 * @param maxDocumentSize
87 * The maximum document size to validate against.
88 *
89 * @throws DocumentToLargeException
90 * If one of the documents in the message is too large or the
91 * documents in aggregate are too large.
92 */
93 public void validateSize(int maxDocumentSize)
94 throws DocumentToLargeException;
95
96 /**
97 * Writes the message from the stream. The message header <b>is</b> written
98 * by this method.
99 *
100 * @param messageId
101 * The id to be assigned to the message.
102 * @param out
103 * The sink for data written.
104 * @throws IOException
105 * On an error writing to the stream.
106 */
107 public void write(int messageId, BsonOutputStream out) throws IOException;
108
109 /**
110 * Writes the message from the stream. The message header <b>is</b> written
111 * by this method.
112 *
113 * @param messageId
114 * The id to be assigned to the message.
115 * @param out
116 * The sink for data written.
117 * @throws IOException
118 * On an error writing to the stream.
119 */
120 public void write(int messageId, BufferingBsonOutputStream out)
121 throws IOException;
122 }