software.amazon.ion.IonContainer Maven / Gradle / Ivy
Show all versions of ion-java Show documentation
/*
* Copyright 2007-2016 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://aws.amazon.com/apache2.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.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;
}