_Private_MarkupCallback.java
/*
* Copyright 2007-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* or in the "license" file accompanying this file. This file 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 com.amazon.ion.impl;
import com.amazon.ion.IonType;
import com.amazon.ion.SymbolToken;
import com.amazon.ion.system.IonTextWriterBuilder;
import com.amazon.ion.util._Private_FastAppendable;
import java.io.IOException;
/**
* NOT FOR APPLICATION USE!
*
*
* Callback for giving users the ability to inject markup into their Ion
* documents.
* <p>
* Customers who want to inject markup into their Ion documents will need to
* extend {@link _Private_MarkupCallback}, implement {@link _Private_CallbackBuilder} to build new
* instances, and pass an instance of their {@link _Private_CallbackBuilder} into
* {@link IonTextWriterBuilder#setCallbackBuilder(_Private_CallbackBuilder)} or
* {@link IonTextWriterBuilder#withCallbackBuilder(_Private_CallbackBuilder)}
* </p>
* <p>
* Note: It is only necessary for subclasses to implement methods they're using
* to inject markup.
* </p>
* <p>
* When all method are called, they are called with (at least) an
* {@link IonType} that represents either the type of data being written or the
* container type that the writer is writing, or currently inside.
* before/afterFieldName and before/afterEachAnnotation get, respectively, the
* field name and annotation that is being written. Methods can use
* {@link #myAppendable} access the output stream.
* </p>
* <h3>Example Calls</h3>
* <p>
* Here are some example call patterns, using the following syntax to show where
* calls will be executed (whitespace is used to increase readability):
*
* <pre>
* <methodName TYPE>
* </pre>
*
* </p>
* <p>
* Input:
*
* <pre>
* { cookies:"Chocolate Chip" }
* </pre>
*
* Output:
*
* <pre>
* <beforeData STRUCT>{<afterStepIn STRUCT>
* <beforeFieldName STRING "cookies"> cookies <afterFieldName STRING "cookies">:<beforeData STRING> "Chocolate Chip" <afterData STRING>
* <beforeStepOut STRUCT>}<afterData STRUCT>
* </pre>
*
* </p>
* <p>
* Input:
*
* <pre>
* anno1::anno2::{
* fname:"John",
* lname:"Smith",
* age:32.785
* }
* </pre>
*
* Output:
*
* <pre>
* <beforeAnnotations STRUCT>
* <beforeEachAnnotation STRUCT "anno1">anno1<afterEachAnnotation STRUCT "anno1">::
* <beforeEachAnnotation STRUCT "anno2">anno2<afterEachAnnotation STRUCT "anno2">::
* <afterAnnotations STRUCT>
* <beforeData STRUCT>{<afterStepIn STRUCT>
* <beforeFieldName STRING "fname">fname<afterFieldName STRING "fname">:<beforeData STRING>"John"<afterData STRING><beforeSeparator STRUCT>,<afterSeparator STRUCT>
* <beforeFieldName STRING "lname">lname<afterFieldName STRING "lname">:<beforeData STRING>"Smith"<afterData STRING><beforeSeparator STRUCT>,<afterSeparator STRUCT>
* <beforeFieldName DECIMAL "age">age<afterFieldName DECIMAL "age">:<beforeData DECIMAL>32.785<afterData DECIMAL>
* <beforeStepOut STRUCT>}<afterData STRUCT>
* </pre>
*
* </p>
* <p>
* Input:
*
* <pre>
* (where (field (this) result) (== (field (curr) majorVersionString) "1.0"))
* </pre>
*
* Output:
*
* <pre>
* <beforeData SEXP>(<afterStepIn SEXP>
* <beforeData SYMBOL>where<afterData SYMBOL><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SEXP>(<afterStepIn SEXP>
* <beforeData SYMBOL>field<afterData SYMBOL><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SEXP>(<afterStepIn SEXP>
* <beforeData SYMBOL>this<afterData SYMBOL>
* <beforeStepOut SEXP>)<afterData SEXP><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SYMBOL>result<afterData SYMBOL>
* <beforeStepOut SEXP>)<afterData SEXP><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SEXP>(<afterStepIn SEXP>
* <beforeData SYMBOL>==<afterData SYMBOL><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SEXP>(<afterStepIn SEXP>
* <beforeData SYMBOL>field<afterData SYMBOL><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SEXP>(<afterStepIn SEXP>
* <beforeData SYMBOL>curr<afterData SYMBOL>
* <beforeStepOut SEXP>)<afterData SEXP><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData SYMBOL>majorVersionString<afterData SYMBOL>
* <beforeStepOut SEXP>)<afterData SEXP><beforeSeparator SEXP> <afterSeparator SEXP>
* <beforeData STRING>"1.0"<afterData STRING>
* <beforeStepOut SEXP>)<afterData SEXP>
* <beforeStepOut SEXP>)<afterData SEXP>
* </pre>
*
* </p>
* <p>
* Input:
*
* <pre>
* 1 5 "Cheesecake" 3.2 true null 'baby tigers' 47e1
* </pre>
*
* Output:
*
* <pre>
* <beforeData INT>1<afterData INT><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData INT>5<afterData INT><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData STRING>"Cheesecake"<afterData STRING><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData DECIMAL>3.2<afterData DECIMAL><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData BOOL>true<afterData BOOL><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData NULL>null<afterData NULL><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData SYMBOL>'baby tigers'<afterData SYMBOL><beforeSeparator DATAGRAM> <afterSeparator DATAGRAM>
* <beforeData FLOAT>470.0e0<afterData FLOAT>
* </pre>
*
* </p>
* <p>
* Input:
*
* <pre>
* [true, 3.4, 3d6, 2.3e8, "string", '''multi-''' '''string''',Symbol, 'qSymbol',
* {{"clob data"}}, {{YmxvYiBkYXRh}}, 1970-06-06, null.struct]
* </pre>
*
* Output:
*
* <pre>
* <beforeData LIST>[<afterStepIn LIST>
* <beforeData BOOL>true<afterData BOOL><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData DECIMAL>3.4<afterData DECIMAL><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData DECIMAL>3d6<afterData DECIMAL><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData FLOAT>2.3E8<afterData FLOAT><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData STRING>"string"<afterData STRING><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData STRING>"multi-string"<afterData STRING><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData SYMBOL>Symbol<afterData SYMBOL><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData SYMBOL>qSymbol<afterData SYMBOL><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData CLOB>{{"clob data"}}<afterData CLOB><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData BLOB>{{YmxvYiBkYXRh}}<afterData BLOB><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData TIMESTAMP>1970-06-06<afterData TIMESTAMP><beforeSeparator LIST>,<afterSeparator LIST>
* <beforeData NULL>null.struct<afterData NULL>
* <beforeStepOut LIST>]<afterData LIST>
* </pre>
*/
public abstract class _Private_MarkupCallback
{
private final _Private_FastAppendable myAppendable;
public _Private_MarkupCallback(_Private_FastAppendable appendable)
{
this.myAppendable = appendable;
}
/**
* Gets the {@link _Private_FastAppendable} that IonWriter will use to write its
* output.
*/
public final _Private_FastAppendable getAppendable()
{
return myAppendable;
}
/**
* Callback to be executed before an Ion value is written. If iType is a
* container type, this is executed before the container's opening
* delimiter. To write data after the opening delimiter use
* {@link #afterStepIn(IonType)}.
* @param iType
* The type of data that will be written.
*/
public void beforeValue(IonType iType)
throws IOException
{
}
/**
* Callback to be executed after an Ion value is written. If iType is a
* container type, this is executed after the container's closing delimiter.
* To write data before the closing delimiter, use
* {@link #beforeStepOut(IonType)}.
* @param iType
* The type of data that was written.
*/
public void afterValue(IonType iType)
throws IOException
{
}
/**
* Callback to be executed before a field name is written.
* @param iType
* The type of data in the field name's corresponding value.
* @param name
* The field name that is being written.
*/
public void beforeFieldName(IonType iType, SymbolToken name)
throws IOException
{
}
/**
* Callback to be executed after a field name is written.
* @param iType
* The type of data in the field name's corresponding value.
* @param name
* The field name that is being written.
*/
public void afterFieldName(IonType iType, SymbolToken name)
throws IOException
{
}
/**
* Callback to be executed after the opening delimiter of a container is
* written. To write data before the opening delimiter, use
* {@link #beforeValue(IonType)}.
* @param containerType
* The type of container that was just stepped into.
*/
public void afterStepIn(IonType containerType)
throws IOException
{
}
/**
* Callback to be executed before the closing delimiter of a container is
* written. To write data after the closing delimiter, use
* {@link #afterValue(IonType)}.
* @param containerType
* The type of container that is about to be stepped out of.
*/
public void beforeStepOut(IonType containerType)
throws IOException
{
}
/**
* Callback to be executed before a separator is written. Called after the
* data has been written, and before the separator. It is called when inside
* all container types, including Sexp, and when not inside a container. It
* is not called after the last element in a container.
* @param containerType
* The type of container the writer is currently in. When writing
* top-level values, the type is DATAGRAM.
*/
public void beforeSeparator(IonType containerType)
throws IOException
{
}
/**
* Callback to be executed after a separator has been written. Called just
* after the separator is written. It is called when inside all container
* types, including Sexp, and when not inside a container. It is not called
* after the last element in a container.
* @param containerType
* The type of container the writer is currently in. When writing
* top-level values, the type is DATAGRAM.
*/
public void afterSeparator(IonType containerType)
throws IOException
{
}
/**
* Callback to be executed before annotations are written. It is executed
* once per set of annotations.
* @param iType
* The type of the data whose annotations are being written.
*/
public void beforeAnnotations(IonType iType)
throws IOException
{
}
/**
* Callback to be executed after annotations are written. It is executed
* once per set of annotations.
* @param iType
* The type of the data whose annotations are being written.
*/
public void afterAnnotations(IonType iType)
throws IOException
{
}
/**
* Callback to be executed before each annotation is written. It is executed
* once per annotation.
* @param iType
* The type of the data whose annotation is being written.
* @param annotation
* The annotation that is being written.
*/
public void beforeEachAnnotation(IonType iType, SymbolToken annotation)
throws IOException
{
}
/**
* Callback to be executed after each annotation is written. It is executed
* once per annotation, before the delimiter.
* @param iType
* The type of the data whose annotation is being written.
* @param annotation
* The annotation that is being written.
*/
public void afterEachAnnotation(IonType iType, SymbolToken annotation)
throws IOException
{
}
}