software.amazon.ion.IonLoader Maven / Gradle / Ivy
Show all versions of ion-java Show documentation
/*
* 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 software.amazon.ion;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
/**
* Loads Ion data in the form of datagrams. These methods parse the input in
* its entirety to identify problems immediately. In contrast, an
* {@link IonReader} will parse one top-level value at a time, and is better
* suited for streaming protocols or large inputs.
*
* WARNING: This interface should not be implemented or extended by
* code outside of this library.
*
* Implementations of this interface are safe for use by multiple
* threads.
*
* @see IonReader
*/
public interface IonLoader
{
/**
* Gets the {@link IonSystem} from which this loader was created.
*
* @return the system instance; not null.
*/
public IonSystem getSystem();
/**
* Gets the {@link IonCatalog} being used by this loader.
*
* @return a catalog; not null.
*/
public IonCatalog getCatalog();
/**
* Loads an entire file of Ion data into a single datagram,
* detecting whether it's text or binary data.
*
* @param ionFile a file containing Ion data.
*
* @return a datagram containing all the values in the file; not null.
*
* @throws IonException if there's a syntax error in the Ion content.
* @throws IOException if reading from the specified file results
* in an IOException.
*/
public IonDatagram load(File ionFile)
throws IonException, IOException;
/**
* Loads Ion text in its entirety.
*
* @param ionText must not be null.
*
* @return a datagram containing the input values; not null.
*
* @throws NullPointerException if ionText is null.
* @throws IonException if there's a syntax error in the Ion content.
*/
public IonDatagram load(String ionText)
throws IonException;
/**
* Loads a stream of Ion text into a single datagram.
*
* The specified reader remains open after this method returns.
*
* Because this library performs its own buffering, it's recommended that
* you avoid adding additional buffering to the given stream.
*
* @param ionText the reader from which to read Ion text.
*
* @return a datagram containing all the elements on the input stream;
* not null.
*
* @throws NullPointerException if ionText is null.
* @throws IonException if there's a syntax error in the Ion content.
* @throws IOException if reading from the specified input stream results
* in an IOException.
*/
public IonDatagram load(Reader ionText)
throws IonException, IOException;
/**
* Loads a block of Ion data into a single datagram,
* detecting whether it's text or binary data.
*
* This method will auto-detect and uncompress GZIPped Ion data.
*
* @param ionData may be either Ion binary data, or UTF-8 Ion text.
* This method assumes ownership of the array and may modify it at
* will.
*
* @return a datagram containing all the values on the input stream;
* not null.
*
* @throws NullPointerException if ionData is null.
* @throws IonException if there's a syntax error in the Ion content.
*/
public IonDatagram load(byte[] ionData)
throws IonException;
/**
*
* WARNING: Will cause a memory leak when reading a gzipped stream, use
* {@link IonLoader#load(IonReader)} instead.
*
*
* Loads an entire stream of Ion data into a single datagram,
* detecting whether it's text or binary data.
*
* The specified stream remains open after this method returns.
*
* This method will auto-detect and uncompress GZIPped Ion data.
*
* Because this library performs its own buffering, it's recommended that
* you avoid adding additional buffering to the given stream.
*
* @param ionData the stream from which to read Ion data.
*
* @return a datagram containing all the values on the input stream;
* not null.
*
* @throws NullPointerException if ionData is null.
* @throws IonException if there's a syntax error in the Ion content.
* @throws IOException if reading from the specified input stream results
* in an IOException.
*
* @deprecated Will cause a memory leak when reading a gzipped stream.
* Use {@link IonLoader#load(IonReader)} instead.
*/
@Deprecated
public IonDatagram load(InputStream ionData)
throws IonException, IOException;
/**
* Loads an entire stream of Ion data into a single datagram,
* detecting whether it's text or binary data.
*
* The specified reader remains open after this method returns.
*
*
* @param reader @param reader source of the Ion data to load.
*
* @return a datagram containing all the values on the reader; not null.
*
* @throws NullPointerException if reader is null.
* @throws IonException if there's a syntax error in the Ion content.
*/
public IonDatagram load(IonReader reader) throws IonException;
}