com.amazon.ion.IonContainer 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.util.Collection;
import java.util.Iterator;

/**
 * Common functionality of Ion struct, list, and
 * sexp types.
 * 
 * WARNING: This interface should not be implemented or extended by
 * code outside of this library.
 */
public interface IonContainer
    extends IonValue, Iterable
{

    /**
     * Returns the number of elements in this container.
     *
     * @return the number of elements, zero if {@code this.isNullValue()}.
     */
    public int size();

    /**
     * Creates an iterator providing the (direct) elements of this container.
     * If this is an {@linkplain #isNullValue() Ion null value}, then this
     * method returns an empty iterator.
     * 

     * Note that iteration over a {@link IonStruct} has unspecified ordering,
     * while iteration over an {@link IonSequence} ({@link IonList} or
     * {@link IonSexp}) must return elements
     * in order of their appearance in the Ion representation.
     *
     * @return a new iterator, not {@code null}.
     */
    public Iterator iterator();


    /**
     * Removes the given element from this container.
     * If this is an {@linkplain #isNullValue() Ion null value}, then this
     * method returns {@code false}.
     * 

     * Note that, unlike {@link Collection#remove(Object)}, this method uses
     * object identity, not {@link Object#equals(Object)}, to find the element.
     * That is, the given instance is removed, not other similarly "equal"
     * instances.
     *
     * @param element the element to be removed from this container,
     * if present.
     * @return true if this container contained the specified
     * element.
     * @throws NullPointerException if the element
     * is null.
     */
    public boolean remove(IonValue element);


    /**
     * Checks if this container is empty.
     *
     * @return true if this container has no contents
     * @throws NullValueException if this container is an Ion
     * null value
     */
    public boolean isEmpty()
        throws NullValueException;

    /**
     * Clears the contents of this container (if any) and set it to empty.
     * If this container is an Ion null value, set it to
     * empty.
     * 

     * Use {@link #makeNull} to make this container null rather than empty.
     * 

     * WARNING: This method is not support for instances of
     * {@link IonDatagram}.
     */
    public void clear();

    /**
     * Sets the contents of this container to an Ion null
     * value.
     * 
     * Use {@link #clear} to make this container empty rather than null.
     */
    public void makeNull();


    public IonContainer clone()
        throws UnknownSymbolException;
}