javax.naming.ldap
인터페이스 LdapContext

모든 슈퍼 인터페이스:

Context, DirContext

알려진 구현 클래스 목록:

InitialLdapContext

public interface LdapContext
extends DirContext 

이 인터페이스는 LDAPv3 스타일의 컨트롤을 가지는 조작과 LDAPv3 스타일의 확장 조작을 실행할 수 있는 컨텍스트를 나타냅니다. 이러한 컨트롤 또는 확장 조작의 어느쪽이나 필요로 하지 않는 어플리케이션의 경우, 보다 범용적인 javax.naming.directory.DirContext를 대신에 사용해 주세요.

컨트롤의 사용에 대한 상세

이 인터페이스는 LDAP v3 컨트롤을 지원 합니다. 높은 레벨로 이 지원를 사용하면, 사용자 프로그램으로 Context/DirContext 메서드를 호출하고 있는 동안에 실행되는 LDAP 조작의 요구 컨트롤을 사용자 프로그램이 설정해, LDAP 조작에 한 결과적으로의 응답 컨트롤의 read를 가능하게 합니다. 구현 레벨에서는 요구 컨트롤과 응답 컨트롤을 올바르게 사용하기 위해서 사용자 프로그램 및 서비스 프로바이더 양쪽 모두의 개발자가 이해할 필요가 있는 상세 사항이 있습니다.

요구 컨트롤

요구 컨트롤에는 다음의 2개의 타입이 있습니다.

• 접속의 작성 방법으로 영향을 주는 요구 컨트롤
• 컨텍스트 메서드에 영향을 주는 요구 컨트롤

접속의 작성 방법으로 영향을 주는 요구 컨트롤은 LDAP 서버와의 접속의 설정 또는 재설정의 어느 쪽의 경우에서도 사용됩니다. 컨텍스트 메서드에 영향을 주는 요구 컨트롤은 다른 모든 LDAP 조작이 LDAP 서버에 보내질 때 사용됩니다. 이것들 2개의 요구 컨트롤에 차이가 생기는 것은 JNDI가 고레벨 API 로 접속을 직접 처리하지 않기 때문입니다. 필요한 접속 관리를 실시하는 것이 서비스 프로바이더의 작업입니다. 따라서, 단일의 접속은 복수의 컨텍스트 인스턴스에 의해 공유되는 일이 있습니다. 서비스 프로바이더는 자유롭게 자신의 알고리즘을 사용해 접속과 네트워크의 사용을 보호합니다. 이와 같이, 메서드가 그 컨텍스트 인스턴스상에서 불려가 면, 서비스 프로바이더는 LDAP 조작에의 대응을 실행할 뿐만 아니라, 접속 관리를 해야 하는 경우도 있습니다. 접속 관리의 경우, 서비스 프로바이더는 「접속 요구 컨트롤」을 사용합니다. 보통 의 LDAP 조작 때는 「컨텍스트 요구 컨트롤」을 사용합니다.

명시적으로 지정되어 있지 않은 경우, 요구 컨트롤이라고 하는 용어는 컨텍스트 요구 컨트롤입니다.

컨텍스트 요구 컨트롤

컨텍스트 인스턴스가 요구 컨트롤을 얻는 방법은 2개 있습니다.

1. ldapContext.newInstance(reqCtls)
2. ldapContext.setRequestControls(reqCtls)

여기서, ldapContext는 LdapContext 인스턴스입니다. reqCtls에 null 또는 비어있는 배열을 지정하면, 요구 컨트롤이 없는 것을 나타냅니다. newInstance()는 reqCtls를 사용해 새로운 인스턴스를 작성합니다. setRequestControls()는 기존의 컨텍스트 인스턴스의 요구 컨트롤을 reqCtls에 갱신합니다.

환경 프로퍼티와는 달라, 컨텍스트 인스턴스의 요구 컨트롤은 그 인스턴스로부터 파생한 컨텍스트 인스턴스에 의해 상속되지 않습니다. 파생한 컨텍스트 인스턴스의 컨텍스트 요구 컨트롤은 null가 됩니다. 파생한 컨텍스트 인스턴스의 요구 컨트롤을 명시적으로 setRequestControls()를 사용해 설정할 필요가 있습니다.

컨텍스트 인스턴스의 요구 컨트롤은 메서드 getRequestControls()를 사용해 취득됩니다.

접속 요구 컨트롤

접속 요구 컨트롤을 설정하는 3개의 방법이 있습니다.

1. new InitialLdapContext(env, connCtls)
2. refException.getReferralContext (env, connCtls)
3. ldapContext.reconnect(connCtls) ;

여기서, refException 은 LdapReferralException 인스턴스, ldapContext는 LdapContext 인스턴스입니다. connCtls에 null 또는 비어있는 배열을 지정하면, 접속 요구 컨트롤이 없는 것을 나타냅니다.

환경 프로퍼티와 같게, 컨텍스트 의 접속 요구 컨트롤은 그 컨텍스트 으로부터 파생한 컨텍스트에 의해 상속됩니다. 일반적으로InitialLdapContext 생성자, 또는 LdapReferralContext.getReferralContext()를 사용해, 접속 요구 컨트롤을 초기화합니다. 이러한 접속 요구 컨트롤은 같은 접속을 공유하고 있는 컨텍스트 즉, 초기 컨텍스트 또는 참조 컨텍스트 으로부터 파생한 컨텍스트에 의해 상속됩니다.

컨텍스트 의 접속 요구 컨트롤을 변경하려면, reconnect()를 사용합니다. ldapContext.reconnect()를 호출하면, ldapContext와 ldapContext로 부터 파생한 새로운 컨텍스트 인스턴스로 사용되고 있는 접속에만 영향을 줍니다. ldapContext와 의 접속을 이전부터 공유하고 있는 컨텍스트은 영향을 받지 않습니다. 즉, 컨텍스트 의 접속 요구 컨트롤은 명시적으로 변경될 필요가 있어, 다른 컨텍스트 의 접속 요구 컨트롤이 변경되어도 영향을 받지 않습니다.

컨텍스트 인스턴스의 접속 요구 컨트롤은 메서드 getConnectControls()를 사용해 취득됩니다.

서비스 프로바이더의 요구

서비스 프로바이더는 접속 및 컨텍스트 의 요구 컨트롤을 다음과 같이 지원 합니다. 컨텍스트 요구 컨트롤은 컨텍스트 인스턴스 마다 관련지어 접속 요구 컨트롤은 접속 인스턴스 마다 관련짓습니다. 서비스 프로바이더는 환경 프로퍼티 「java.naming.ldap.control.connect」내에서 접속 요구 컨트롤을 검색해, 이 환경 프로퍼티를 프로바이더가 작성하는 컨텍스트 인스턴스에 인도하지 않으면 안됩니다.

응답 컨트롤

LdapContext.getResponseControls() 라고 하는 메서드는 Context/DirContext 조작을 호출한 결과 행해진 LDAP 조작으로 생성된 응답 컨트롤을 얻는 데 사용됩니다. 이 결과는 암묵적인 재접속을 포함한 LDAP 조작의 아래에서 생성된 모든 응답 컨트롤입니다. 재접속 응답 컨트롤만을 취득하려면, reconnect()와 거기에 계속되는 getResponseControls()를 사용합니다.

파라미터

모든 메서드에 파라미터로서 건네받는 Control[] 배열은 호출측이 소유합니다. 서비스 프로바이더는 배열을 변경하지 않고, 그 배열에 대한 참조도 보관 유지합니다만, 배열내의 개별의 Control 객체에 대한 참조를 보관 유지하는 일이 있습니다. 모든 메서드로 리턴된 Control[] 배열은 불변으로 이 배열이 리턴된 뒤도, 호출측 또는 서비스 프로바이더의 어느쪽이나 이 배열을 변경할 수 없습니다.

도입된 버전 :

1.3

관련 항목:

InitialLdapContext, LdapReferralException.getReferralContext(java.util.Hashtable, javax.naming.ldap.Control[])

필드 개요

static String

CONTROL_FACTORIES 사용하는 컨트롤 팩토리의 리스트를 지정하기 위한, 환경 프로퍼티의 이름을 보관 유지하는 정수입니다.

인터페이스 javax.naming.directory. DirContext 로부터 상속된 필드

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

인터페이스 javax.naming. Context 로부터 상속된 필드

APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

메서드 개요

ExtendedResponse	extendedOperation (ExtendedRequest request) 확장 조작을 실행합니다.
Control []	getConnectControls () 이 컨텍스트에 유효한 접속 요구 컨트롤을 취득합니다.
Control []	getRequestControls () 이 컨텍스트에 유효한 요구 컨트롤을 취득합니다.
Control []	getResponseControls () 이 컨텍스트 으로 마지막에 불려 간 메서드의 결과로서 생성된 응답 컨트롤을 취득합니다.
LdapContext	newInstance (Control [] requestControls) 이 컨텍스트 의 새로운 인스턴스를 요구 컨트롤을 사용해 생성합니다.
void	reconnect (Control [] connCtls) 지정된 컨트롤과 이 컨텍스트 환경을 사용해 LDAP 서버에 재접속합니다.
void	setRequestControls (Control [] requestControls) 이 컨텍스트 으로 계속해 호출되는 메서드에 요구 컨트롤을 설정합니다.

인터페이스 javax.naming.directory. DirContext 로부터 상속된 메서드

bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search

인터페이스 javax.naming. Context 로부터 상속된 메서드

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

필드의 상세

CONTROL_FACTORIES

static final String  CONTROL_FACTORIES

사용하는 컨트롤 팩토리의 리스트를 지정하기 위한, 환경 프로퍼티의 이름을 보관 유지하는 정수입니다. 프로퍼티의 값은 지정된 다른 컨트롤로부터 컨트롤을 작성하는 팩토리 클래스의 완전 수식 클래스명의 구두점으로 단락지은 리스트로 할 필요가 있습니다. 상세한 것에 대하여는 ControlFactory.getControlInstance()를 참조하십시오. 이 프로퍼티는 환경, 애플릿 파라미터, 시스템 프로퍼티, 또는 1개 이상의 resource file로 지정됩니다.

이 정수의 값은 「java.naming.factory.control」입니다.

관련 항목:

ControlFactory, Context.addToEnvironment(java.lang.String, java.lang.Object), Context.removeFromEnvironment(java.lang.String), 정수 필드값

메서드의 상세

extendedOperation

ExtendedResponse  extendedOperation(ExtendedRequest  request)
                                   throws NamingException 

확장 조작을 실행합니다.이 메서드를 사용해, LDAPv3 확장 조작을 지원 합니다.

파라미터:

request - 실행하는 null 이외의 요구

반환값:

null 가능성이 있는 조작의 응답. null은 조작을 해도 응답은 아무것도 생성되지 않는 것을 나타낸다

예외:

NamingException - 확장 조작 실행중에 에러가 발생했을 경우

newInstance

LdapContext  newInstance(Control [] requestControls)
                        throws NamingException 

이 컨텍스트 의 새로운 인스턴스를 요구 컨트롤을 사용해 생성합니다.이 메서드는 multi-thread의 액세스를 위해서 이 컨텍스트 인스턴스를 새롭게 작성하는 편리한 수법입니다. 예를 들어 복수의 thread가 각각 다른 컨텍스트 요구 컨트롤을 사용하고 싶은 경우, 각 thread는 다른 thread와 동기 할 필요가 없고, 이 메서드를 사용해, 이 컨텍스트 독자적인 복사본을 취득해, 컨텍스트 요구 컨트롤을 설정 또는 취득할 수 있습니다.

새로운 컨텍스트에 는 이 컨텍스트과 같은 환경 프로퍼티, 접속 요구 컨트롤이 있습니다. 상세한 것에 대하여는 클래스에 대한 기술을 참조하십시오. 이 컨텍스트과 새로운 컨텍스트 의 사이로 같은 네트워크 접속 또는 그 외의 자원을 공유할 수도 있습니다. 다만, 각 컨텍스트 의 사이에 경합이 발생하는 경우는 공유할 수 없습니다.

파라미터:

requestControls - 새로운 컨텍스트에 사용하는 null 가능성이 있는 요구 컨트롤. null인 경우는 요구 컨트롤을 사용하지 않고 초기화된다

반환값:

null 이외의 LdapContext 인스턴스

예외:

NamingException - 새로운 인스턴스의 작성중에 에러가 발생했을 경우

관련 항목:

InitialLdapContext

reconnect

void reconnect(Control [] connCtls)
               throws NamingException 

지정된 컨트롤과 이 컨텍스트 환경을 사용해 LDAP 서버에 재접속합니다.

이 메서드는 LDAP 바인드 조작을 명시적으로 초기화하는 방법입니다. 이 메서드를 사용해, LDAP 바인드 조작에 요구 컨트롤을 설정하거나 또는 그 조작에 의해 리턴된 응답 컨트롤을 취득하기 위해서 명시적으로 서버에 접속할 수 있습니다.

이 메서드에서는 이 컨텍스트 의 connCtls를 새로운 접속 요구 컨트롤이 되도록 설정합니다. 이 컨텍스트 의 컨텍스트 요구 컨트롤은 영향을 받지 않습니다. 이 메서드가 불려가 면, 그 후에 계속되는 암묵적인 재접속이 connCtls를 사용해 실행됩니다. connCtls는 또, 접속 요구 컨트롤로서 이 컨텍스트 으로부터 파생한 새로운 컨텍스트 인스턴스에도 사용됩니다. 이러한 접속 요구 컨트롤은, setRequestControls() 영향을 받지 않습니다.

구현의 상세한 것에 대하여는 구현측인 서비스 프로바이더는 클래스의 「서비스 프로바이더」섹션을 잘 읽어 주세요.

파라미터:

connCtls - null 가능성이 있는 사용하기 위한 컨트롤. null인 경우, 컨트롤은 사용되지 않는다

예외:

NamingException - 재접속중에 에러가 발생했을 경우

관련 항목:

getConnectControls(), newInstance(javax.naming.ldap.Control[])

getConnectControls

Control [] getConnectControls()
                             throws NamingException 

이 컨텍스트에 유효한 접속 요구 컨트롤을 취득합니다. 컨트롤은 JNDI 구현이 소유하고 있어, 불변입니다. 배열, 컨트롤의 어느쪽이나, 호출측은 변경할 수 없습니다.

반환값:

null 가능성이 있는 컨트롤의 배열. null은 이 컨텍스트에 대해서 컨트롤이 설정되어 있지 않은 것을 나타낸다

예외:

NamingException - 요구 컨트롤의 취득중에 에러가 발생했을 경우

setRequestControls

void setRequestControls(Control [] requestControls)
                        throws NamingException 

이 컨텍스트 으로 계속해 호출되는 메서드에 요구 컨트롤을 설정합니다. 이 요구 컨트롤은 JNDI 구현이 소유하고 있어, 불변입니다. 배열, 컨트롤의 어느쪽이나, 호출측은 변경할 수 없습니다.

이전의 요구 컨트롤을 모두 삭제해, 계속해 이 컨텍스트 으로 호출되는 메서드가 사용하기 위해서 requestControls를 추가합니다.

requestControls는 다음에 setRequestControls()를 호출할 때까지 유효합니다. 더 이상 컨텍스트 메서드에 영향을 주고 싶지 않은 경우는 컨트롤을 해제하기 위해서 null 또는 비어있는 배열을 가지는 setRequestControls()를 명시적으로 호출할 필요가 있습니다. 이 컨텍스트에 효과적인 요구 컨트롤을 확인하려면, getRequestControls()를 사용합니다.

파라미터:

requestControls - null 가능성이 있는 사용하기 위한 컨트롤. null인 경우, 컨트롤은 사용되지 않는다

예외:

NamingException - 요구 컨트롤의 설정중에 에러가 발생했을 경우

관련 항목:

getRequestControls()

getRequestControls

Control [] getRequestControls()
                             throws NamingException 

이 컨텍스트에 유효한 요구 컨트롤을 취득합니다. 이 요구 컨트롤은 JNDI 구현이 소유하고 있어, 불변입니다. 배열, 컨트롤의 어느쪽이나, 호출측은 변경할 수 없습니다.

반환값:

null 가능성이 있는 컨트롤의 배열. null은 이 컨텍스트에 대해서 요구 컨트롤이 설정되어 있지 않은 것을 나타낸다

예외:

NamingException - 요구 컨트롤의 취득중에 에러가 발생했을 경우

관련 항목:

setRequestControls(javax.naming.ldap.Control[])

getResponseControls

Control [] getResponseControls()
                              throws NamingException 

이 컨텍스트 으로 마지막에 불려 간 메서드의 결과로서 생성된 응답 컨트롤을 취득합니다. 이 응답 컨트롤은 JNDI 구현이 소유하고 있어, 불변입니다. 배열, 컨트롤의 어느쪽이나, 호출측은 변경할 수 없습니다.

이러한 응답 컨트롤에는 정상적으로 종료한 조작 또는 실패한 조작에 의해 생성된 것이 있습니다.

응답 컨트롤을 돌려줄 수 있는 컨텍스트 메서드가 불려가 면, 이전의 메서드 호출로부터의 응답 컨트롤은 모두 해제됩니다. getResponseControls()는 LDAP 서버로부터 받은 순서로 컨텍스트 메서드가 조작한 LDAP에 의해 생성되는 모든 응답 컨트롤을 리턴합니다. getResponseControls()를 호출하면, 이전의 응답 컨트롤은 해제되지 않습니다. 컨트롤을 돌려줄 수 있는 다음의 컨텍스트 메서드가 불려 갈 때까지 몇 번이라도 호출하거나 같은 컨트롤을 되돌리거나 하는 것이 가능합니다.

반환값:

null 가능성이 있는 컨트롤의 배열. null인 경우, 이 컨텍스트 으로 불려 간 이전의 메서드는 컨트롤을 생성하고 있지 않다

예외:

NamingException - 응답 컨트롤의 취득중에 에러가 발생했을 경우