/*
* Copyright (c) 2016, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
*
* WSO2 Inc. licenses this file to you under the Apache License,
* Version 2.0 (the "License"); you may not use this file except
* in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.wso2.carbon.mediator.datamapper.engine.input.builders;
import java.io.IOException;
/**
* Interface for implement the methods to create generic data holding model of data mapper engine
*/
public interface Builder {
/**
* Method for writing start marker of a Array value.
* <p/>
* <p/>
* Array values can be written in any context where values
* are allowed: meaning everywhere except for when
* a field name is expected.
*/
void writeStartArray() throws IOException;
/**
* Method for writing closing marker of a Array.
* <p/>
* <p/>
* Marker can be written if the innermost structured type
* is Array.
*/
void writeEndArray() throws IOException;
/**
* Method for writing starting marker of a Object value.
* <p/>
* <p/>
* Object values can be written in any context where values
* are allowed: meaning everywhere except for when
* a field name is expected.
*/
void writeStartObject() throws IOException;
/**
* Method for writing closing marker of a Object value.
* <p/>
* <p/>
* Marker can be written if the innermost structured type
* is Object, and the last written event was either a
* complete value, or START-OBJECT marker
*/
void writeEndObject() throws IOException;
/**
* Method for writing a field name.
* <p/>
* <p/>
* Field names can only be written in Object context , when field name is expected
*/
void writeFieldName(String name) throws IOException;
/**
* Method for outputting a String value. Depending on context
* this means either array element, (object) field value or
* a stand alone String; but in all cases, String will be
* surrounded in double quotes, and contents will be properly
* escaped.
*/
void writeString(String text) throws IOException;
/**
* Method that will output given chunk of binary data as base64
* encoded, as a complete String value (surrounded by double quotes).
* This method defaults
* <p/>
* Alternatively if linefeeds are not included,
* resulting String value may violate the requirement of base64
* RFC which mandates line-length of 76 characters and use of
* linefeeds. However, all Parser implementations
* are required to accept such "long line base64"; as do
* typical production-level base64 decoders.
*/
void writeBinary(byte[] data, int offset, int len) throws IOException;
/**
* Method for outputting given value as number.
* Can be called in any context where a value is expected
* (Array value, Object field value, root-level value).
*
* @param number Number value to write
*/
void writeNumber(int number) throws IOException;
/**
* Method for outputting indicate JSON numeric value.
* Can be called in any context where a value is expected
* (Array value, Object field value, root-level value).
*
* @param number Number value to write
*/
void writeNumber(double number) throws IOException;
/**
* Method for outputting literal boolean value (one of
* Strings 'true' and 'false').
* Can be called in any context where a value is expected
* (Array value, Object field value, root-level value).
*/
void writeBoolean(boolean state) throws IOException;
/*
/**********************************************************
/*Convenience field write methods
/**********************************************************
*/
/**
* Convenience method for outputting a field entry ("member")
* that has a String value. Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeString(value);
* </pre>
*/
void writeStringField(String fieldName, String value) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* that has a String value. Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeString(value);
* </pre>
*/
void writeField(String fieldName, Object value, String fieldType) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* that has a boolean value. Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeBoolean(value);
* </pre>
*/
void writeBooleanField(String fieldName, boolean value) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* that has the specified numeric value. Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeNumber(value);
* </pre>
*/
void writeNumberField(String fieldName, int value) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* that has the specified numeric value. Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeNumber(value);
* </pre>
*/
void writeNumberField(String fieldName, double value) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* that contains specified data in base64-encoded form.
* Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeBinary(value);
* </pre>
*/
void writeBinaryField(String fieldName, byte[] data) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* (that will contain a JSON Array value), and the START_ARRAY marker.
* Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeStartArray();
* </pre>
* <p/>
* Note: caller still has to take care to close the array
* (by calling {#link #writeEndArray}) after writing all values
* of the value Array.
*/
void writeArrayFieldStart(String fieldName) throws IOException;
/**
* Convenience method for outputting a field entry ("member")
* (that will contain a JSON Object value), and the START_OBJECT marker.
* Equivalent to:
* <pre>
* writeFieldName(fieldName);
* writeStartObject();
* </pre>
* <p/>
* Note: caller still has to take care to close the Object
* (by calling {#link #writeEndObject}) after writing all
* entries of the value Object.
*/
void writeObjectFieldStart(String fieldName) throws IOException;
/**
* Method called to close builder, so that no more content
* can be written.
*/
void close() throws IOException;
/**
* Methid called to get the final content after closing the builder
*
* @return built content
* @throws IOException
*/
String getContent() throws IOException;
/**
* Convenience method for outputting a primitive
* that has a primitive value.
*/
void writePrimitive(Object value, String fieldType) throws IOException;
}