java.util
인터페이스 Collection

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

BeanContext , BeanContextServices , List , Set , SortedSet

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

AbstractCollection , AbstractList , AbstractSet , ArrayList , BeanContextServicesSupport , BeanContextSupport , HashSet , LinkedHashSet , LinkedList , TreeSet , Vector

public interface Collection

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

「Bag」또는 「멀티 세트」(중복 요소를 저장할 수 있는 순서 붙이고가 없는 콜렉션)은 이 인터페이스를 직접 구현할 필요가 있습니다.

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

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

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

도입된 버젼:

1.2

관련 항목:

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

메소드의 개요

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

메소드의 상세

size

public int size()

콜렉션의 요소수를 돌려줍니다. 이 콜렉션에 Integer.MAX_VALUE 보다 많은 요소가 있는 경우는 Integer.MAX_VALUE 를 돌려줍니다.

반환값:

콜렉션의 요소수

isEmpty

public boolean isEmpty()

콜렉션에 요소가 없는 경우에 true 를 돌려줍니다.

반환값:

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

contains

public boolean contains(Object  o)

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

파라미터:

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

반환값:

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

예외:

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

NullPointerException - 지정된 요소가 null 로, 이 콜렉션이 null 요소를 서포트하지 않는 경우 (임의의 옵션)

iterator

public Iterator  iterator()

콜렉션의 요소의 반복자를 돌려줍니다. 요소가 돌려주어지는 순서에 대한 프로텍션은 없습니다. 다만, 이 콜렉션이, 프로텍션을 제공하는 클래스의 인스턴스인 경우는 예외입니다.

반환값:

이 콜렉션의 요소의 Iterator

toArray

public Object [] toArray()

콜렉션의 모든 요소가 저장되고 있는 배열을 돌려줍니다. 반복자에 의해 돌려주어지는 요소의 순서를 프로텍션하고 있는 콜렉션의 경우, 이 메소드는 같은 순서로 요소를 돌려주지 않으면 안됩니다.

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

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

반환값:

콜렉션의 모든 요소가 저장되고 있는 배열

toArray

public Object [] toArray(Object [] 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

public boolean add(Object  o)

콜렉션이 지정된 요소를 저장하도록(듯이) 합니다 (임의의 오퍼레이션). 이 호출의 결과, 콜렉션이 변경되었을 경우는 true 를 돌려줍니다. 이 콜렉션이 중복을 허가하지 않고 벌써 지정된 요소를 저장하고 있는 경우는 false 를 돌려줍니다.

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

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

파라미터:

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

반환값:

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

예외:

UnsupportedOperationException - 이 콜렉션이 add 를 서포트하지 않는 경우

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

NullPointerException - 지정된 요소가 null 로, 이 콜렉션이 null 요소를 서포트하지 않는 경우

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

remove

public 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

public boolean containsAll(Collection  c)

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

파라미터:

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

반환값:

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

예외:

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

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

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

관련 항목:

contains(Object)

addAll

public boolean addAll(Collection  c)

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

파라미터:

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

반환값:

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

예외:

UnsupportedOperationException - 이 콜렉션이 addAll 메소드를 서포트하지 않는 경우

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

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

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

관련 항목:

add(Object)

removeAll

public boolean removeAll(Collection  c)

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

파라미터:

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

반환값:

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

예외:

UnsupportedOperationException - 이 콜렉션이 removeAll 메소드를 서포트하지 않는 경우

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

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

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

관련 항목:

remove(Object) , contains(Object)

retainAll

public boolean retainAll(Collection  c)

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

파라미터:

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

반환값:

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

예외:

UnsupportedOperationException - 콜렉션이 retainAll 메소드를 서포트하고 있지 않는 경우

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

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

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

관련 항목:

remove(Object) , contains(Object)

clear

public void clear()

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

예외:

UnsupportedOperationException - 이 콜렉션이 clear 메소드를 서포트하지 않는 경우

equals

public 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

public 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)