java.util
인터페이스 Collection<E>

모든 슈퍼 인터페이스:

Iterable <E>

알려진 서브 인터페이스 목록 :

BeanContext, BeanContextServices, BlockingQueue <E>, List <E>, Queue <E>, Set <E>, SortedSet <E>

알려진 구현 클래스 목록:

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentLinkedQueue, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingQueue, LinkedHashSet, LinkedList, PriorityBlockingQueue, PriorityQueue, RoleList, RoleUnresolvedList, Stack, SynchronousQueue, TreeSet, Vector

public interface Collection<E>
extends Iterable <E>

「컬렉션 계층」 루트 인터페이스입니다. 컬렉션은 그 「요소」인 객체의 그룹을 나타냅니다. 컬렉션에 따라서는 요소의 중복을 허용합니다만, 허가하지 않는 컬렉션도 있습니다. 또, 순서 붙일 수 있는 컬렉션과 그렇지 않은 컬렉션이 있습니다. JDK는 이 인터페이스의 「직접」의 구현을 일절 제공하지 않습니다. Set 및 List와 같은 보다 용도의 특정된 서브 인터페이스를 제공합니다. 이 인터페이스는 일반적으로 최대한의 보편성이 요구되는 장면에서 컬렉션을 건네주거나 그 컬렉션을 조작하기 위해서 사용됩니다.

「Bag」또는 「멀티 세트」(중복 요소를 포함할 수 있는 정렬가 없는 컬렉션)은 이 인터페이스를 직접 구현할 필요가 있습니다.

범용 Collection 구현 클래스 (보통, 서브 인터페이스를 개입시켜 간접적으로 Collection를 구현한다)는 2개의 「표준」생성자를 제공하지 않으면 안됩니다. 비어있는 컬렉션을 작성하는 void (인수 없음) 생성자과Collection 형의 인수를 1개 가져, 그 인수와 같은 요소로 새로운 컬렉션을 작성하는 생성자 입니다. 따라서, 후자의 생성자에서는 사용자는 어느 컬렉션에서도 카피할 수 있어 희망의 구현형의 컬렉션과 완전하게 같은 컬렉션을 생성할 수 있습니다. 이 규약은 무 지워지고 있는 것은 아닙니다만 (인터페이스는 생성자를 포함할 수 없기 때문에), Java 플랫폼 라이브러리에 있어서의 모든 범용 Collection 구현은 이 규약에 준거하고 있습니다.

이 컬렉션이 오퍼레이션을 지원 하고 있지 않는 경우, 이 인터페이스 (처리되는 컬렉션을 수정하는 메서드)에 포함되어 있는 「파괴적인」메서드는 UnsupportedOperationException을 Throw 하도록 지정되고 있습니다. 이 때, 호출이 컬렉션에 영향을 주지 않는 경우, 이러한 메서드는 UnsupportedOperationException을 Throw 할 수 있습니다 만, 필수가 아닙니다. 예를 들어 추가된 컬렉션이 비어있는 경우, 변경 불가능한 컬렉션으로 addAll(Collection)를 호출하면, = 예외를 발생시킬 수 있습니다만, 필수가 아닙니다.

컬렉션의 구현에는 포함할 수 있는 요소에 제한이 있는 것도 있습니다. 예를 들어 null 요소를 금지하는 구현이나, null 요소의 형태에 제한이 있는 구현도 있습니다. 부적격인 요소를 추가하려고 하면, 보통 NullPointerException 또는 ClassCastException와 같은 체크되지 않는 예외를 Throw 합니다. 부적격인 요소가 있을지 어떨지를 조회하려고 하면, 예외를 Throw 하는 경우나, 다만 false를 돌려주는 경우도 있습니다. 전의 동작을 표시하는 구현도 있으면, 후의 동작을 표시하는 구현도 있습니다. 많은 경우는 컬렉션에의 삽입이 되지 않는 부적격인 요소를 처리하려고 하면, 구현에 의해 예외가 Throw 되거나 처리가 유효하게 됩니다. 이 인터페이스에 관한 그러한 예외는 「임의」의 사양으로서 마크 됩니다.

이 인터페이스는 Java Collections Framework 멤버입니다.

Collections Framework 인터페이스내의 다수의 메서드는 equals 메서드와의 관련으로 정의됩니다. 예를 들어, contains(Object o) 메서드의 사양은 「이 컬렉션에 (o==null ? e==null : o.equals(e))를 채우는 요소 e가 1개 이상 포함되는 경우에게만, true를 돌려준다」라고 하는 것입니다. 이 사양은 「null 이외의 인수 o를 사용해 Collection.contains를 호출하면, 요소 e로 o.equals(e)가 불려 간다」라고 이해해야 하지는 않습니다. 최적화의 구현 방법은 자유롭기 때문에 2개의 요소의 해시 코드를 비교하는 등 방법으로 equals 호출은 피할 수 있는 (Object.hashCode() 사양에서는 등가가 아닌 해시 코드를 보관 유지하는 2개의 객체는 등가가 아닌 것이 보증된다). 보통, Collections Framework 인터페이스의 다양한 구현으로 구현자가 적절이라고 판단한다면, 기반이 되는 Object 메서드의 지정된 동작을 자유롭게 이용할 수 있습니다.

도입된 버전 :

1.2

관련 항목:

Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollection

메서드 개요

boolean	add (E o) 컬렉션이 지정된 요소를 포함하도록 합니다 (임의의 오퍼레이션).
boolean	addAll (Collection <? extends E > c) 지정된 컬렉션의 모든 요소를 이 컬렉션에 추가합니다 (임의의 오퍼레이션).
void	clear () 컬렉션으로부터 모든 요소를 삭제합니다 (임의의 오퍼레이션).
boolean	contains (Object o) 컬렉션으로 지정된 요소가 있는 경우에 true를 리턴합니다.
boolean	containsAll (Collection <? > c) 이 컬렉션내에 지정된 컬렉션의 모든 요소가 있는 경우에 true를 리턴합니다.
boolean	equals (Object o) 지정된 객체와 이 컬렉션이 동일한지 어떤지를 비교합니다.
int	hashCode () 컬렉션의 해시 코드값을 리턴합니다.
boolean	isEmpty () 컬렉션에 요소가 없는 경우에 true를 리턴합니다.
Iterator <E >	iterator () 컬렉션의 요소의 반복자를 리턴합니다.
boolean	remove (Object o) 지정된 요소의 1개의 인스턴스가 이 컬렉션내에 있는 경우에 그것을 이 컬렉션으로부터 삭제합니다 (임의의 오퍼레이션).
boolean	removeAll (Collection <? > c) 지정된 컬렉션에도 포함되고 있는 이 컬렉션의 모든 요소를 삭제합니다 (임의의 오퍼레이션).
boolean	retainAll (Collection <? > c) 이 컬렉션에 대해, 지정된 컬렉션에 포함되고 있는 요소만을 보관 유지합니다 (임의의 오퍼레이션).
int	size () 컬렉션의 요소수를 리턴합니다.
Object []	toArray () 컬렉션의 모든 요소가 포함되고 있는 배열을 리턴합니다.
<T> T[]	toArray (T[] a) 이 컬렉션내의 모든 요소를 보관 유지하는 배열을 리턴합니다.

메서드의 상세

size

int size()

컬렉션의 요소수를 리턴합니다. 이 컬렉션에 Integer.MAX_VALUE 보다 많은 요소가 있는 경우는 Integer.MAX_VALUE를 리턴합니다.

반환값:

컬렉션의 요소수

isEmpty

boolean isEmpty()

컬렉션에 요소가 없는 경우에 true를 리턴합니다.

반환값:

컬렉션에 요소가 없는 경우는 true

contains

boolean contains(Object  o)

컬렉션으로 지정된 요소가 있는 경우에 true를 리턴합니다. 즉, 이 컬렉션에 (o==null ? e==null : o.equals(e)) 인 요소 e가 1개 이상 있는 경우에만 true를 리턴합니다.

파라미터:

o - 컬렉션에 있을지 어떨지를 조사하는 요소

반환값:

컬렉션으로 지정된 요소가 있는 경우는 true

예외:

ClassCastException - 지정한 요소의 형태가 이 컬렉션과 호환이 아닌 경우 (임의의 옵션)

NullPointerException - 지정된 요소가 null 로 이 컬렉션이 null 요소를 지원 하지 않는 경우 (임의의 옵션)

iterator

Iterator <E > iterator()

컬렉션의 요소의 반복자를 리턴합니다. 요소가 리턴된 순서에 대한 보증은 없습니다. 다만, 이 컬렉션이, 보증을 제공하는 클래스의 인스턴스인 경우는 예외입니다.

정의:

인터페이스 Iterable <E > 내의 iterator

반환값:

이 컬렉션의 요소의 Iterator

toArray

Object [] toArray()

컬렉션의 모든 요소가 포함되고 있는 배열을 리턴합니다. 반복자에 의해 리턴된 요소의 순서를 보증하고 있는 컬렉션의 경우, 이 메서드는 같은 순서로 요소를 돌려주지 않으면 안됩니다.

리턴된 배열에의 참조를 컬렉션이 유지하지 않는다고 하는 점으로써, 이 배열은 안전합니다. 즉, 이 메서드는 컬렉션이 배열을 기본으로 하고 있는 경우에서도 새로운 배열을 할당합니다. 이 때문에 호출측은 리턴된 배열을 자유롭게 변경할 수 있습니다.

메서드는 배열 베이스의 API와 컬렉션 베이스의 API 사이의 중개역으로서 기능합니다.

반환값:

컬렉션의 모든 요소가 포함되고 있는 배열

toArray

<T> T[] toArray(T[] a)

이 컬렉션내의 모든 요소를 보관 유지하는 배열을 리턴합니다. 리턴된 배열의 실행시의 형태는 지정된 배열의 형태입니다. 컬렉션이 지정된 배열에 들어가는 경우는 그 중에 리턴됩니다 . 그렇지 않은 경우는 지정된 배열의 실행시의 형태와 컬렉션의 사이즈를 가지는 새로운 배열을 할당할 수 있습니다.

컬렉션이 지정된 배열에 들어가 그 배열에 또한 여유가 있는 경우 (즉, 배열이 컬렉션보다 많은 요소를 가지는 경우), 그 배열내에서 컬렉션의 종단보다 나머지의 요소는 null로 설정됩니다. 컬렉션에 null 요소가 없는 것을 호출해 옆이 알고 있는 경우에만, 이 특성을 이용해 컬렉션의 길이를 판단할 수 있습니다.

반복자에 의해 요소가 리턴된 순서를 컬렉션이 보증하는 경우, 이 메서드는 같은 순서로 요소를 돌려주지 않으면 안됩니다.

toArray 메서드와 같이, 이 메서드는 배열 베이스의 API와 컬렉션 베이스의 API 사이의 중개역으로서 기능합니다. 게다가 이 메서드에서는 출력 배열의 실행시의 형태를 정확하게 제어할 수 있기 때문에 환경에 따라서는 할당의 수고를 억제할 수 있습니다 .

l가 캐릭터 라인만으로부터 되는 List 인 것을 알 수 있고 있으면 가정합니다. 다음의 코드를 사용하면, 새롭게 할당할 수 있었던 String 배열에 리스트의 덤프를 수집할 수 있습니다.

     String[] x = (String[]) v.toArray(new String[0]);
 

toArray(new Object[0])는 기능의 점으로써 toArray()와 동일합니다.

파라미터:

a - 컬렉션의 요소의 포함처의 배열. 배열의 사이즈가 충분하지 않은 경우는 같은 실행시의 형태로 새로운 배열이 포함용으로서 할당할 수 있다

반환값:

컬렉션의 요소를 포함한 배열

예외:

ArrayStoreException - 지정된 배열의 실행시의 형태가 이 컬렉션의 각 요소의 실행시의 형태의 슈퍼타입이 아닌 경우

NullPointerException - 지정된 배열이 null 인 경우

add

boolean add(E  o)

컬렉션이 지정된 요소를 포함하도록 합니다 (임의의 오퍼레이션). 이 호출의 결과, 컬렉션이 변경되었을 경우는 true를 리턴합니다. 이 컬렉션이 중복을 허가하지 않고, 이미 지정된 요소를 포함하고 있는 경우는 false를 리턴합니다.

이 오퍼레이션을 지원하는 컬렉션에서는 컬렉션에 추가할 수 있는 요소에 대해 제한이 있는 경우가 있습니다. 특히, 컬렉션에 따라서는 null 요소의 추가가 거부되는 경우나, 추가할 수 있는 요소의 형태가 제한되는 경우가 있습니다. 추가할 수 있는 요소의 제한에 대해서는 해당하는 컬렉션 클래스의 문서에 명기하도록의해 주세요.

그 요소가 이미 있다고 하는 이외의 이유로써 특정의 요소의 추가를 거부하는 경우, 컬렉션은 false를 돌려주는 것이 아니라 예외를 Throw 할 필요가 있습니다. 이것에 의해 이 호출이 돌아온 뒤에 컬렉션이 지정된 요소를 반드시 포함한다고 하는 불변성을 유지할 수 있습니다 .

파라미터:

o - 컬렉션에 있을지 어떨지를 조사하는 요소

반환값:

이 호출의 결과, 이 컬렉션이 변경되었을 경우는 true

예외:

UnsupportedOperationException - 이 컬렉션이 add를 지원 하지 않는 경우

ClassCastException - 지정된 요소의 클래스가 원인으로 이 컬렉션에 추가할 수 없었던 경우

NullPointerException - 지정된 요소가 null 로 이 컬렉션이 null 요소를 지원 하지 않는 경우

IllegalArgumentException - 이 요소의 특성이 원인으로 이 컬렉션에 추가할 수 없었던 경우

remove

boolean remove(Object  o)

지정된 요소의 1개의 인스턴스가 이 컬렉션내에 있는 경우에 그것을 이 컬렉션으로부터 삭제합니다 (임의의 오퍼레이션). 즉, (o==null ? e==null : o.equals(e)) 인 요소 e가 컬렉션내에 1개 이상 포함되고 있는 경우에 이것을 삭제합니다. 지정된 요소가 컬렉션내에 포함되고 있었을 경우에는 true를 리턴합니다. 즉, 이 호출의 결과, 컬렉션이 변경되었을 경우에 true를 리턴합니다.

파라미터:

o - 컬렉션으로부터 삭제되는 요소 (그 요소가 있는 경우)

반환값:

이 호출의 결과, 이 컬렉션이 변경되었을 경우는 true

예외:

ClassCastException - 지정한 요소의 형태가 이 컬렉션과 호환이 아닌 경우 (임의의 옵션)

NullPointerException - 지정된 요소가 null 로 이 컬렉션이 null 요소를 지원 하지 않는 경우 (임의의 옵션)

UnsupportedOperationException - 이 컬렉션이 remove를 지원 하지 않는 경우

containsAll

boolean containsAll(Collection <? > c)

이 컬렉션내에 지정된 컬렉션의 모든 요소가 있는 경우에 true를 리턴합니다.

파라미터:

c - 이 컬렉션에 있을지 어떨지를 조사하는 컬렉션

반환값:

지정된 컬렉션의 모든 요소가 이 컬렉션내에 있는 경우는 true

예외:

ClassCastException - 지정된 컬렉션의 1개 또는 복수의 요소의 형태가 이 컬렉션과 호환이 아닌 경우 (임의의 옵션)

NullPointerException - 지정된 컬렉션이 1개 또는 복수의 null 요소를 포함해, 이 컬렉션이 null 요소를 지원 하지 않는 경우 (임의의 옵션)

NullPointerException - 지정된 컬렉션이 null 인 경우

관련 항목:

contains(Object)

addAll

boolean addAll(Collection <?  extends E > c)

지정된 컬렉션의 모든 요소를 이 컬렉션에 추가합니다 (임의의 오퍼레이션). 오퍼레이션의 진행중에 지정된 컬렉션이 변경되었을 경우의, 이 오퍼레이션의 동작은 정의되지 않습니다. 따라서, 지정된 컬렉션이 이 컬렉션 자신이며, 이 컬렉션이 비어있지 않은 경우, 이 호출의 동작은 정의되지 않습니다.

파라미터:

c - 컬렉션에 삽입되는 요소

반환값:

이 호출의 결과, 이 컬렉션이 변경되었을 경우는 true

예외:

UnsupportedOperationException - 이 컬렉션이 addAll 메서드를 지원 하지 않는 경우

ClassCastException - 지정된 컬렉션의 요소의 클래스가 원인으로 이 컬렉션에 추가할 수 없었던 경우

NullPointerException - 지정된 컬렉션내에 1개 또는 복수의 null 요소가 포함되지 않고, 이 컬렉션이 null 요소를 지원 하지 않는 경우. 또는 지정된 컬렉션이 null인 경우

IllegalArgumentException - 지정된 컬렉션의 요소의 특성이 원인으로 이 컬렉션에 추가할 수 없었던 경우

관련 항목:

add(Object)

removeAll

boolean removeAll(Collection <? > c)

지정된 컬렉션에도 포함되고 있는 이 컬렉션의 모든 요소를 삭제합니다 (임의의 오퍼레이션). 이 호출의 결과, 이 컬렉션에는 지정된 컬렉션과 공통의 요소는 없어집니다.

파라미터:

c - 컬렉션으로부터 삭제되는 요소

반환값:

이 호출의 결과, 이 컬렉션이 변경되었을 경우는 true

예외:

UnsupportedOperationException - 이 컬렉션이 removeAll 메서드를 지원 하지 않는 경우

ClassCastException - 이 컬렉션의 1개 또는 복수의 요소의 형태가 지정된 컬렉션과 호환이 아닌 경우 (임의의 옵션)

NullPointerException - 이 컬렉션이 1개 또는 복수의 null 요소를 포함해, 지정된 컬렉션이 null 요소를 지원 하지 않는 경우 (임의의 옵션)

NullPointerException - 지정된 컬렉션이 null 인 경우

관련 항목:

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection <? > c)

이 컬렉션에 대해, 지정된 컬렉션에 포함되고 있는 요소만을 보관 유지합니다 (임의의 오퍼레이션). 즉, 지정된 컬렉션에 포함되어 있지 않은 모든 요소를 이 컬렉션으로부터 삭제합니다.

파라미터:

c - 컬렉션으로 보관 유지되는 요소

반환값:

이 호출의 결과, 이 컬렉션이 변경되었을 경우는 true

예외:

UnsupportedOperationException - 컬렉션이 retainAll 메서드를 지원 하고 있지 않는 경우

ClassCastException - 이 컬렉션의 1개 또는 복수의 요소의 형태가 지정된 컬렉션과 호환이 아닌 경우 (임의의 옵션)

NullPointerException - 이 컬렉션이 1개 또는 복수의 null 요소를 포함해, 지정된 컬렉션이 null 요소를 지원 하지 않는 경우 (임의의 옵션)

NullPointerException - 지정된 컬렉션이 null 인 경우

관련 항목:

remove(Object), contains(Object)

clear

void clear()

컬렉션으로부터 모든 요소를 삭제합니다 (임의의 오퍼레이션). 이 호출의 결과, 예외를 Throw 하지 않는 한, 컬렉션은 비웁니다.

예외:

UnsupportedOperationException - 이 컬렉션이 clear 메서드를 지원 하지 않는 경우

equals

boolean equals(Object  o)

지정된 객체와 이 컬렉션이 동일한지 어떤지를 비교합니다.

Collection 인터페이스는 Object.equals 범용 규약에 조항을 추가합니다만, Collection를 「직접」에 구현하는 (즉, Collection 이며, Set 또는 List가 아닌 클래스를 작성한다) 때로는 Object.equals를 오버라이드(override) 하는 경우에 배려가 필요합니다. Object.equals를 오버라이드(override) 할 필요가 없는 경우, 가장 단순한 방법은 Object 구현에 의존된 것입니다만, 구현에 따라서는 디폴트의 「참조 비교」대신에 「값비교」를 구현할 필요가 있는 일이 있습니다. List 및 Set에 서는 이러한 값비교가 필요합니다.

Object.equals 메서드의 일반 규약에의하면 equals는 대칭적이지 않으면 안됩니다 (즉, b.equals(a)인 경우에만 a.equals(b)). List.equals 및 Set.equals 규약에의하면 리스트는 다른 리스트와만 동일해져, 세트는 다른 세트와만 동일해집니다. 이 때문에 List와 Set 어느 쪽의 인터페이스도 구현하지 않는 컬렉션 클래스의 커스텀 equals 메서드는 이 컬렉션이 리스트 또는 세트라고 비교되었을 경우에 false를 리턴합니다. 같은 논리에의해 Set와 List 양인터페이스를 올바르게 구현하는 클래스를 기술할 수 없습니다.

오버라이드(override):

클래스 Object 내의 equals

파라미터:

o - 이 컬렉션과 동일한지 어떤지가 비교되는 Object

반환값:

지정된 객체가 이 컬렉션에 동일한 경우는 true

관련 항목:

Object.equals(Object), Set.equals(Object), List.equals(Object)

hashCode

int hashCode()

컬렉션의 해시 코드값을 리턴합니다. Collection 인터페이스는 Object.hashCode 메서드의 일반 규약에 조항을 추가합니다만, 프로그래밍에 대해, Object.equals 메서드를 오버라이드(override) 하는 클래스는 Object.hashCode 메서드의 일반 규약을 채우기 위해서 Object.hashCode 메서드도 오버라이드(override) 해야 하는 것에 주의해 주세요. 특히, c1.equals(c2)는 c1.hashCode() ==c2.hashCode()를 의미합니다.

오버라이드(override):

클래스 Object 내의 hashCode

반환값:

이 컬렉션의 해시 코드값

관련 항목:

Object.hashCode(), Object.equals(Object)