com.amazon.ion.IonLoader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ion-java Show documentation
A Java implementation of the Amazon Ion data notation.
The newest version!
/*
 * 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;

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;
}