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 또는 빈 상태(empty)의 배열을 지정하면(자), 요구 컨트롤이 없는 것을 나타냅니다. newInstance() 는,reqCtls 를 사용해 새로운 인스턴스를 작성합니다. setRequestControls() 는, 기존의 문맥 인스턴스의 요구 컨트롤을 reqCtls 에 갱신합니다.

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

문맥 인스턴스의 요구 컨트롤은, 메소드 getRequestControls() 를 사용해 검출됩니다.

접속 요구 컨트롤

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

1. 신규의 InitialLdapContext(env, connCtls)
2. refException.getReferralContext (env, connCtls)
3. ldapContext.reconnect(connCtls) ;

여기서,refException 은 LdapReferralException 의 인스턴스,ldapContext 는 LdapContext 의 인스턴스입니다. connCtls 에 null 또는 빈 상태(empty)의 배열을 지정하면(자), 접속 요구 컨트롤이 없는 것을 나타냅니다.

환경 프로퍼티과 같게, 문맥의 접속 요구 컨트롤은, 그 문맥으로부터 파생한 문맥에 의해 상속됩니다. 일반적으로은,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 또는 빈 상태(empty)의 배열을 가지는 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 - 응답 컨트롤의 취득중에, 에러가 발생했을 경우