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

모든 슈퍼 인터페이스:

Iterable <E>

기존의 서브 인터페이스의 일람:

BeanContext , BeanContextServices , BlockingDeque <E>, BlockingQueue <E>, Deque <E>, List <E>, NavigableSet <E>, Queue <E>, Set <E>, SortedSet <E>

기존의 구현 클래스의 일람:

AbstractCollection , AbstractList , AbstractQueue , AbstractSequentialList , AbstractSet , ArrayBlockingQueue , ArrayDeque , ArrayList , AttributeList , BeanContextServicesSupport , BeanContextSupport , ConcurrentLinkedQueue , ConcurrentSkipListSet , CopyOnWriteArrayList , CopyOnWriteArraySet , DelayQueue , EnumSet , HashSet , JobStateReasons , LinkedBlockingDeque , 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 개(살)의 「표준」생성자 을 제공하지 않으면 안됩니다. 빈 상태(empty)의 컬렉션을 작성하는 void (인수 없음) 생성자 과Collection 형의 인수를 1 개 가져, 그 인수와 같은 요소로 새로운 컬렉션을 작성하는 생성자 입니다. 따라서, 후자의 생성자 에서는, 사용자는 어느 컬렉션에서도 카피할 수 있어 희망의 구현형의 컬렉션과 완전하게 같은 컬렉션을 생성할 수 있습니다. 이 규약은 의무 지워지고 있는 것은 아닙니다만 (인터페이스는 생성자 을 포함할 수 없기 때문에), Java 플랫폼 라이브러리에 있어서의 모든 범용 Collection 의 구현은 이 규약에 준거하고 있습니다.

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

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

독자적인 동기 정책를 결정할지 어떨지는, 각각의 컬렉션에 따라서 다릅니다. 구현에 의한 강한 보증이 없는 경우, 다른 thread에 의해 변경되는 컬렉션으로 메소드를 호출하면(자), 정의되어 있지 않은 동작이 발생할 가능성이 있습니다. 이것에는, 직접적인 호출해, 호출을 실행할 가능성이 있는 메소드에의 컬렉션의 인도해, 및 기존의 반복자를 사용한 컬렉션의 검사가 포함됩니다.

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 메소드의 지정된 동작을 자유롭게 이용할 수 있습니다.

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

도입된 버젼:

1.2

관련 항목:

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

메소드의 개요

boolean	add (E e) 지정된 요소가 이 컬렉션에 포함되고 있는 것을 보증합니다 (임의의 오퍼레이션).
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 의 사이의 중개역으로서 기능합니다. 게다가 이 메소드에서는, 출력 배열의 실행시의 형태를 정확하게 제어할 수 있기 (위해)때문에, 환경에 따라서는 할당의 수고를 억제할 수가 있습니다.

x 가, 캐릭터 라인만으로부터 되는 컬렉션인 것을 알 수 있고 있으면(자) 가정합니다. 다음의 코드를 사용하면(자), 새롭게 할당할 수 있었던 String 의 배열에 컬렉션을 덤프 할 수 있습니다.

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

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

파라미터:

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

반환값:

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

예외:

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

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

add

boolean add(E  e)

지정된 요소가 이 컬렉션에 포함되고 있는 것을 보증합니다 (임의의 오퍼레이션). 이 호출의 결과, 컬렉션이 변경되었을 경우는 true 를 돌려줍니다. 이 컬렉션이 요소의 중복을 허가하지 않고, 지정된 요소가 벌써 포함되어 있는 경우는 false 를 돌려줍니다.

이 오퍼레이션을 지원하는 컬렉션에서는, 컬렉션에 추가할 수 있는 요소에 대해 제한이 있는 경우가 있습니다. 예를 들어, 컬렉션에 따라서는,null 요소의 추가가 허가되지 않는 것이나, 추가되는 요소의 형태를 제한하는 일이 있습니다. 추가되는 요소에 관해서 제한이 있는 경우는, 그 Collection 클래스의 문서에 명시해야 하겠지요.

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

파라미터:

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

반환값:

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

예외:

UnsupportedOperationException - add 오퍼레이션이 이 컬렉션으로 지원되지 않는 경우

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

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

IllegalArgumentException - 요소가 있는 특성이 원인으로, 이 컬렉션에 요소를 추가할 수 없는 경우

IllegalStateException - 삽입 제한을 위해서(때문에) 이 시점에서 요소를 추가할 수 없는 경우

remove

boolean remove(Object  o)

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

파라미터:

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

반환값:

이 호출의 결과, 요소가 삭제되었을 경우는 true

예외:

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

NullPointerException - 지정된 요소가 null 로, 이 컬렉션이 null 요소를 허용 하지 않는 경우 (생략 가능)

UnsupportedOperationException - remove 오퍼레이션이 이 컬렉션으로 지원되지 않는 경우

containsAll

boolean containsAll(Collection <? > c)

이 컬렉션내에, 지정된 컬렉션의 모든 요소가 있는 경우에 true 를 돌려줍니다.

파라미터:

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

반환값:

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

예외:

ClassCastException - 지정된 컬렉션의 1 개 이상의 요소의 형태가, 이 컬렉션과 호환이 아닌 경우 (생략 가능)

NullPointerException - 지정된 컬렉션에 1 개 이상의 null 요소가 포함되어 있어 이 컬렉션이 null 요소를 허가하지 않는 경우 (생략 가능). 또는 지정된 컬렉션이 null 의 경우

관련 항목:

contains(Object)

addAll

boolean addAll(Collection <?  extends E > c)

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

파라미터:

c - 컬렉션에 추가되는 요소를 포함한 컬렉션

반환값:

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

예외:

UnsupportedOperationException - addAll 오퍼레이션이 이 컬렉션으로 지원되지 않는 경우

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

NullPointerException - 지정된 컬렉션내에 null 요소가 포함되어 이 컬렉션이 null 요소를 허가하지 않는 경우. 또는 지정된 컬렉션이 null 의 경우

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

IllegalStateException - 삽입 제한을 위해, 이 시점에서 일부의 요소를 추가할 수 없는 경우

관련 항목:

add(Object)

removeAll

boolean removeAll(Collection <? > c)

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

파라미터:

c - 이 컬렉션으로부터 삭제되는 요소를 포함한 컬렉션

반환값:

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

예외:

UnsupportedOperationException - removeAll 메소드가 이 컬렉션으로 지원되지 않는 경우

ClassCastException - 이 컬렉션의 1 개 이상의 요소의 형태가, 지정된 컬렉션과 호환이 아닌 경우 (생략 가능)

NullPointerException - 이 컬렉션내에 1 개 이상의 null 요소가 포함되어 있어 지정된 컬렉션이 null 요소를 지원하지 않는 경우 (생략 가능). 또는 지정된 컬렉션이 null 의 경우

관련 항목:

remove(Object) , contains(Object)

retainAll

boolean retainAll(Collection <? > c)

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

파라미터:

c - 이 컬렉션으로 보관 유지되는 요소를 포함한 컬렉션

반환값:

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

예외:

UnsupportedOperationException - retainAll 오퍼레이션이 이 컬렉션으로 지원되지 않는 경우

ClassCastException - 이 컬렉션의 1 개 이상의 요소의 형태가, 지정된 컬렉션과 호환이 아닌 경우 (생략 가능)

NullPointerException - 이 컬렉션내에 1 개 이상의 null 요소가 포함되어 있어 지정된 컬렉션이 null 요소를 허가하지 않는 경우 (생략 가능). 또는 지정된 컬렉션이 null 의 경우

관련 항목:

remove(Object) , contains(Object)

clear

void clear()

이 컬렉션으로부터 모든 요소를 삭제합니다 (임의의 오퍼레이션). 이 메소드가 돌아오면(자), 컬렉션은 비웁니다.

예외:

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 - 이 컬렉션과 동일한지 어떤지가 비교되는 객체

반환값:

지정된 객체가 이 컬렉션에 동일한 경우는 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)