br.com.objectos.collections.base.MutableCollection Maven / Gradle / Ivy
/*
* Copyright (C) 2021-2022 Objectos Software LTDA.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License 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 br.com.objectos.collections.base;
/**
* A mutable {@link BaseCollection}.
*
*
* This interface extends the {@code BaseCollection} interface by providing
* additional methods for adding elements to the collection.
*
* @param type of the elements in this collection
*
* @since 2
*
* @see BaseCollection
*/
public interface MutableCollection extends BaseCollection {
/**
* Adds all elements of the given {@link Iterable} to this collection.
*
*
* Elements are added in the order they are returned by the given iterable's
* iterator. If the iterator returns a {@code null} element then this method
* does not return and throws a {@link NullPointerException} instead.
*
* @param elements
* the elements to be added to this collection
*
* @return {@code true} if this collection changed as a result of this
* operation
*/
boolean addAllIterable(Iterable elements);
/**
* Adds the specified element {@code e} to this collection or throws a
* {@code NullPointerException} if the element is {@code null}.
*
*
* If a {@code NullPointerException} is to be thrown, the {@code nullMessage}
* value is used as the exception's message.
*
*
* Typical usage:
*
*
* coll.addWithNullMessage(value, "value == null");
*
* @param e
* an element to be added to this collection
* @param nullMessage
* the {@code NullPointerException} message
*
* @return {@code true} if this collection changed as a result of this
* operation
*/
boolean addWithNullMessage(E e, Object nullMessage);
/**
* Adds the specified element {@code e} to this collection or throws a
* {@code NullPointerException} if the element is {@code null}.
*
*
* If a {@code NullPointerException} is to be thrown, the concatenation of
* {@code nullMessageStart}, {@code index} and {@code nullMessageEnd} is
* used as the exception's message.
*
*
* Typical usage:
*
*
* coll.addWithNullMessage(element, "elements[", index, "] == null");
*
* @param e
* an element to be added to this collection
* @param nullMessageStart
* the first part of the {@code NullPointerException} message
* @param index
* the second part of the {@code NullPointerException} message
* @param nullMessageEnd
* the third part of the {@code NullPointerException} message
*
* @return {@code true} if this collection changed as a result of this
* operation
*/
boolean addWithNullMessage(E e, Object nullMessageStart, int index, Object nullMessageEnd);
}