View Javadoc
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 }