001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.modeshape.schematic.internal.document;
017
018import java.io.IOException;
019import java.io.OutputStream;
020import java.io.Writer;
021import java.util.Date;
022import java.util.UUID;
023import java.util.regex.Pattern;
024import org.modeshape.schematic.document.Binary;
025import org.modeshape.schematic.document.Code;
026import org.modeshape.schematic.document.CodeWithScope;
027import org.modeshape.schematic.document.Document;
028import org.modeshape.schematic.document.MaxKey;
029import org.modeshape.schematic.document.MinKey;
030import org.modeshape.schematic.document.ObjectId;
031import org.modeshape.schematic.document.Symbol;
032import org.modeshape.schematic.document.Timestamp;
033
034/**
035 * A component that writes modified JSON representations from the in-memory {@link Document} representation.
036 * <p>
037 * The modified JSON format is nearly identical to the JSON serialization used by MongoDB. All standard JSON values are written as
038 * expected, but the types unique to BSON are written as follows:
039 * <table border="1" cellspacing="0" cellpadding="3">
040 * <tr>
041 * <th>BSON Type</th>
042 * <th>Class</th>
043 * <th>Format</th>
044 * <th>Example</th>
045 * </tr>
046 * <tr>
047 * <td>Symbol</td>
048 * <td>{@link Symbol}</td>
049 * <td>"<i>value</i>"</td>
050 * <td>"The quick brown fox"</td>
051 * </tr>
052 * <tr>
053 * <td>Regular Expression</td>
054 * <td>{@link Pattern}</td>
055 * <td>{ "$regex" : "<i>pattern</i>", "$options" : "<i>flags</i>" }</td>
056 * <td>{ "$regex" : "[CH]at\sin", "$options" : "im" }</td>
057 * </tr>
058 * <tr>
059 * <td>Date</td>
060 * <td>{@link Date}</td>
061 * <td>{ "$date" : "<i>yyyy-MM-dd</i>T<i>HH:mm:ss</i>Z" }</td>
062 * <td>{ "$date" : "2011-06-11T08:44:25Z" }</td>
063 * </tr>
064 * <tr>
065 * <td>Timestamp</td>
066 * <td>{@link Timestamp}</td>
067 * <td>{ "$ts" : <i>timeValue</i>, "$inc" : <i>incValue</i> }</td>
068 * <td>"\/TS("2011-06-11T08:44:25Z")\/"</td>
069 * </tr>
070 * <tr>
071 * <td>ObjectId</td>
072 * <td>{@link ObjectId}</td>
073 * <td>{ "$oid" : "<i>12bytesOfIdInBase16</i>" }</td>
074 * <td>{ "$oid" : "0000012c0000c8000900000f" }</td>
075 * </tr>
076 * <tr>
077 * <td>Binary</td>
078 * <td>{@link Binary}</td>
079 * <td>{ "$type" : <i>typeAsInt</i>, "$base64" : "<i>bytesInBase64</i>" }"</td>
080 * <td>{ "$type" : 0, "$base64" : "TWFuIGlzIGRpc3R" }"</td>
081 * </tr>
082 * <tr>
083 * <td>UUID</td>
084 * <td>{@link UUID}</td>
085 * <td>{ "$uuid" : "<i>string-form-of-uuid</i>" }</td>
086 * <td>{ "$uuid" : "09e0e949-bba4-459c-bb1d-9352e5ee8958" }</td>
087 * </tr>
088 * <tr>
089 * <td>Code</td>
090 * <td>{@link Code}</td>
091 * <td>{ "$code" : "<i>code</i>" }</td>
092 * <td>{ "$code" : "244-I2" }</td>
093 * </tr>
094 * <tr>
095 * <td>CodeWithScope</td>
096 * <td>{@link CodeWithScope}</td>
097 * <td>{ "$code" : "<i>code</i>", "$scope" : <i>scope document</i> }</td>
098 * <td>{ "$code" : "244-I2", "$scope" : { "name" : "Joe" } }</td>
099 * </tr>
100 * <tr>
101 * <td>MinKey</td>
102 * <td>{@link MinKey}</td>
103 * <td>"MinKey"</td>
104 * <td>"MinKey"</td>
105 * </tr>
106 * <tr>
107 * <td>MaxKey</td>
108 * <td>{@link MaxKey}</td>
109 * <td>"MaxKey"</td>
110 * <td>"MaxKey"</td>
111 * </tr>
112 * <tr>
113 * <td>Null value</td>
114 * <td></td>
115 * <td>null</td>
116 * <td>null</td>
117 * </tr>
118 * </table>
119 * </p>
120 * 
121 * @author Randall Hauch <rhauch@redhat.com> (C) 2011 Red Hat Inc.
122 */
123public interface JsonWriter {
124
125    /**
126     * Write to the supplied stream the modified JSON representation of the supplied in-memory {@link Document}.
127     * 
128     * @param object the BSON object or BSON value; may not be null
129     * @param stream the output stream; may not be null
130     * @throws IOException if there was a problem reading from the stream
131     */
132    void write( Object object,
133                OutputStream stream ) throws IOException;
134
135    /**
136     * Write to the supplied writer the modified JSON representation of the supplied in-memory {@link Document}.
137     * 
138     * @param object the BSON object or BSON value; may not be null
139     * @param writer the writer; may not be null
140     * @throws IOException if there was a problem reading from the stream
141     */
142    void write( Object object,
143                Writer writer ) throws IOException;
144
145    /**
146     * Write to the supplied string builder the modified JSON representation of the supplied in-memory {@link Document} .
147     * 
148     * @param object the BSON object or BSON value; may not be null
149     * @param builder the string builder; may not be null
150     */
151    void write( Object object,
152                StringBuilder builder );
153
154    /**
155     * Write and return the modified JSON representation of the supplied in-memory {@link Document}.
156     * 
157     * @param object the BSON object or BSON value; may not be null
158     * @return the JSON string representation; never null
159     */
160    String write( Object object );
161}