001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
005 *
006 * The contents of this file are subject to the terms of either the GNU
007 * General Public License Version 2 only ("GPL") or the Common Development
008 * and Distribution License("CDDL") (collectively, the "License").  You
009 * may not use this file except in compliance with the License.  You can
010 * obtain a copy of the License at
011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
012 * or LICENSE.txt.  See the License for the specific
013 * language governing permissions and limitations under the License.
014 *
015 * When distributing the software, include this License Header Notice in each
016 * file and include the License file at LICENSE.txt.
017 *
018 * GPL Classpath Exception:
019 * Oracle designates this particular file as subject to the "Classpath"
020 * exception as provided by Oracle in the GPL Version 2 section of the License
021 * file that accompanied this code.
022 *
023 * Modifications:
024 * If applicable, add the following below the License Header, with the fields
025 * enclosed by brackets [] replaced by your own identifying information:
026 * "Portions Copyright [year] [name of copyright owner]"
027 *
028 * Contributor(s):
029 * If you wish your version of this file to be governed by only the CDDL or
030 * only the GPL Version 2, indicate your decision by adding "[Contributor]
031 * elects to include this software in this distribution under the [CDDL or GPL
032 * Version 2] license."  If you don't indicate a single choice of license, a
033 * recipient has the option to distribute your version of this file under
034 * either the CDDL, the GPL Version 2 or to extend the choice of license to
035 * its licensees as provided above.  However, if you add GPL Version 2 code
036 * and therefore, elected the GPL Version 2 license, then the option applies
037 * only if the new code is made subject to such option by the copyright
038 * holder.
039 */
040
041package javax.json;
042
043import java.util.Collection;
044import java.util.Map;
045
046/**
047 * Factory to create {@link JsonObjectBuilder} and {@link JsonArrayBuilder}
048 * instances. If a factory instance is configured with some configuration,
049 * that would be used to configure the created builder instances.
050 *
051 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonBuilderFactory>
052 * 
053 * <BR /><BR />
054 * {@code JsonObjectBuilder} and {@code JsonArrayBuilder} can also be created
055 * using {@link Json}'s methods. If multiple builder instances are created,
056 * then creating them using a builder factory is preferred.
057 * 
058 * <DIV CLASS=EXAMPLE>{@code
059 * JsonBuilderFactory factory = Json.createBuilderFactory(...);
060 * 
061 * JsonArray value = factory
062 *      .createArrayBuilder()
063 *      .add(factory.createObjectBuilder()
064 *          .add("type", "home")
065 *          .add("number", "212 555-1234"))
066 *      .add(factory.createObjectBuilder()
067 *          .add("type", "fax")
068 *          .add("number", "646 555-4567"))
069 *      .build();
070 * }</DIV>
071 *
072 * <BR />All the methods in this class are safe for use by multiple concurrent
073 * threads.
074 */
075public interface JsonBuilderFactory {
076
077    /**
078     * Creates a {@code JsonObjectBuilder} instance that is used to build
079     * {@link JsonObject}.
080     *
081     * @return a JSON object builder
082     */
083    JsonObjectBuilder createObjectBuilder();
084
085    /**
086     * Creates a {@code JsonObjectBuilder} instance, initialized with an object.
087     *
088     * @param object the initial object in the builder
089     * @return a JSON object builder
090     * @throws NullPointerException if specified object is {@code null}
091     *
092     * @since 1.1
093     */
094    default JsonObjectBuilder createObjectBuilder(JsonObject object) {
095        throw new UnsupportedOperationException();
096    }
097
098    /**
099     * Creates a {@code JsonObjectBuilder} instance, initialized with the specified object.
100     *
101     * @param object the initial object in the builder
102     * @return a JSON object builder
103     * @throws NullPointerException if specified object is {@code null}
104     *
105     * @since 1.1
106     */
107    default JsonObjectBuilder createObjectBuilder(Map<String, Object> object) {
108        throw new UnsupportedOperationException();
109    }
110
111    /**
112     * Creates a {@code JsonArrayBuilder} instance that is used to build
113     * {@link JsonArray}
114     *
115     * @return a JSON array builder
116     */
117    JsonArrayBuilder createArrayBuilder();
118
119    /**
120     * Creates a {@code JsonArrayBuilder} instance, initialized with an array.
121     *
122     * @param array the initial array in the builder
123     * @return a JSON array builder
124     * @throws NullPointerException if specified array is {@code null}
125     *
126     * @since 1.1
127     */
128    default JsonArrayBuilder createArrayBuilder(JsonArray array) {
129        throw new UnsupportedOperationException();
130    }
131
132    /**
133     * Creates a {@code JsonArrayBuilder} instance,
134     * initialized with the content of specified collection.
135     *
136     * @param collection the initial data for the builder
137     * @return a JSON array builder
138     * @throws NullPointerException if specified collection is {@code null}
139     *
140     * @since 1.1
141     */
142    default JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
143        throw new UnsupportedOperationException();
144    }
145
146    /**
147     * Returns read-only map of supported provider specific configuration
148     * properties that are used to configure the created JSON builders.
149     * If there are any specified configuration properties that are not
150     * supported by the provider, they won't be part of the returned map.
151     *
152     * @return a map of supported provider specific properties that are used
153     * to configure the builders. The map be empty but not null.
154     */
155    Map<String, ?> getConfigInUse();
156
157}