Interface LdapContext

public interface LdapContext
extends DirContext

이 인터페이스는 LDAPv3 스타일 제어로 연산을 수행하고 LDAPv3 스타일 확장 연산을 수행할 수 있는 컨텍스트를 나타내요. 그런 제어나 확장 연산이 필요하지 않은 애플리케이션은 더 일반적인 javax.naming.directory.DirContext를 대신 사용해야 해요.

제어에 대한 사용 세부 사항

이 인터페이스는 LDAP v3 제어에 대한 지원을 제공해요. 높은 수준에서 이 지원은 사용자 프로그램이 Context/DirContext 메서드를 호출하는 과정에서 실행되는 LDAP 연산에 대한 요청 제어(request controls)를 설정하고, LDAP 연산에서 비롯된 응답 제어(response controls)를 읽을 수 있게 해 줘요. 구현 수준에는 사용자 프로그램과 서비스 공급자 양쪽의 개발자가 요청·응답 제어를 올바르게 사용하기 위해 이해해야 할 몇 가지 세부 사항이 있어요.

요청 제어(Request Controls). 요청 제어에는 두 가지 유형이 있어요:

연결이 만들어지는 방식에 영향을 주는 요청 제어
컨텍스트 메서드에 영향을 주는 요청 제어

전자는 LDAP 서버와 연결을 수립하거나 재수립해야 할 때마다 사용돼요. 후자는 다른 모든 LDAP 연산이 LDAP 서버로 보내질 때 사용돼요. 이 두 유형의 요청 제어를 구분할 필요가 있는 이유는 JNDI가 연결과 직접 다루지 않는 고수준 API이기 때문이에요. 필요한 연결 관리를 하는 것은 서비스 공급자의 일이에요. 결과적으로 단일 연결이 여러 컨텍스트 인스턴스에서 공유될 수 있고, 서비스 공급자는 연결과 네트워크 사용을 보존하기 위한 자체 알고리즘을 자유롭게 사용할 수 있어요. 따라서 컨텍스트 인스턴스에서 메서드가 호출될 때, 서비스 공급자는 대응하는 LDAP 연산을 수행하는 것 외에 어떤 연결 관리를 해야 할 수도 있어요. 연결 관리에는 연결 요청 제어를 사용하고, 정상 LDAP 연산에는 컨텍스트 요청 제어를 사용해요. 명시적으로 한정하지 않는 한, "요청 제어"라는 용어는 컨텍스트 요청 제어를 가리켜요.

컨텍스트 요청 제어(Context Request Controls). 컨텍스트 인스턴스가 요청 제어를 얻는 방법은 두 가지가 있어요.

ldapContext.newInstance(reqCtls)
ldapContext.setRequestControls(reqCtls)

여기서 ldapContext는 LdapContext의 인스턴스예요. reqCtls에 null이나 빈 배열을 지정하면 요청 제어가 없는 것을 의미해요. newInstance()는 reqCtls를 사용해 새 컨텍스트 인스턴스를 만들고, setRequestControls()는 기존 컨텍스트 인스턴스의 요청 제어를 reqCtls로 갱신해요. 환경 속성과 달리, 컨텍스트 인스턴스의 요청 제어는 그로부터 파생된 컨텍스트 인스턴스가 상속하지 않아요. 파생된 컨텍스트 인스턴스는 컨텍스트 요청 제어로 null을 가져요. 파생된 컨텍스트 인스턴스의 요청 제어는 setRequestControls()로 명시적으로 설정해야 해요. 컨텍스트 인스턴스의 요청 제어는 getRequestControls() 메서드를 사용해 가져와요.

연결 요청 제어(Connection Request Controls). 연결 요청 제어가 설정되는 방법은 세 가지가 있어요.

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

여기서 refException은 LdapReferralException의 인스턴스이고, ldapContext는 LdapContext의 인스턴스예요. connCtls에 null이나 빈 배열을 지정하면 연결 요청 제어가 없는 것을 의미해요. 환경 속성처럼, 컨텍스트의 연결 요청 제어는 그로부터 파생된 컨텍스트가 상속해요. 일반적으로 InitialLdapContext 생성자나 LdapReferralContext.getReferralContext()로 연결 요청 제어를 초기화해요. 이 연결 요청 제어들은 같은 연결을 공유하는 컨텍스트들 — 즉 초기 컨텍스트나 referral 컨텍스트에서 파생된 컨텍스트들 — 이 상속해요. 컨텍스트의 연결 요청 제어를 바꾸려면 reconnect()를 사용해요. ldapContext.reconnect()를 호출하면 ldapContext가 사용하는 연결과 ldapContext에서 파생된 새 컨텍스트 인스턴스에만 영향을 줘요. 이전에 ldapContext와 연결을 공유했던 컨텍스트들은 변경되지 않아요. 즉 컨텍스트의 연결 요청 제어는 명시적으로 변경되어야 하며, 다른 컨텍스트의 연결 요청 제어 변경에 영향을 받지 않아요. 컨텍스트 인스턴스의 연결 요청 제어는 getConnectControls() 메서드를 사용해 가져와요.

서비스 공급자 요구 사항(Service Provider Requirements). 서비스 공급자는 연결·컨텍스트 요청 제어를 다음 방식으로 지원해요. 컨텍스트 요청 제어는 컨텍스트 인스턴스별로 연결되어야 하고, 연결 요청 제어는 연결 인스턴스별로 연결되어야 해요. 서비스 공급자는 환경 속성 "java.naming.ldap.control.connect"에서 연결 요청 제어를 찾고, 이 환경 속성을 자신이 만드는 컨텍스트 인스턴스에 전달해야 해요.

응답 제어(Response Controls). LdapContext.getResponseControls() 메서드는 Context/DirContext 연산을 호출한 결과로 실행된 LDAP 연산이 생성한 응답 제어를 가져오는 데 사용돼요. 결과는 암시적 재연결을 포함한 기반 LDAP 연산이 생성한 모든 응답 제어예요. 재연결 응답 제어만 얻으려면 reconnect() 다음에 getResponseControls()를 사용해요.

매개변수. 어떤 메서드에 매개변수로 전달되는 Control[] 배열은 호출자가 소유해요. 서비스 공급자는 배열을 수정하거나 참조를 유지하지 않지만, 배열 안의 개별 Control 객체들에 대한 참조는 유지할 수 있어요. 어떤 메서드가 반환하는 Control[] 배열은 불변(immutable)이며, 호출자나 서비스 공급자 중 누구도 이후에 수정해서는 안 돼요.

CONTROL_FACTORIES

static final String CONTROL_FACTORIES

사용할 제어 팩토리 목록을 지정하기 위한 환경 속성의 이름을 담는 상수예요. 속성의 값은 다른 제어가 주어지면 제어를 만들 팩토리 클래스의 완전히 한정된 클래스 이름의 콜론으로 구분된 목록이어야 해요. 자세한 내용은 ControlFactory.getControlInstance()를 참조하세요. 이 속성은 환경, 시스템 속성, 또는 하나 이상의 리소스 파일에서 지정될 수 있어요. 이 상수의 값은 "java.naming.factory.control"이에요.

See Also: ControlFactory, Context.addToEnvironment(java.lang.String, java.lang.Object), Context.removeFromEnvironment(java.lang.String), 상수 필드 값(Constant Field Values)

extendedOperation

ExtendedResponse extendedOperation(ExtendedRequest request)
                            throws NamingException

확장 연산을 수행해요. 이 메서드는 LDAPv3 확장 연산을 지원하는 데 사용돼요.

Parameters: request - 수행할, null이 아닌 요청
Returns: 연산의, null일 수 있는 응답. null은 연산이 어떤 응답도 생성하지 않았음을 의미해요
Throws: NamingException - 확장 연산을 수행하는 동안 오류가 발생했을 때

newInstance

LdapContext newInstance(Control[] requestControls)
                 throws NamingException

요청 제어를 사용해 초기화된 이 컨텍스트의 새 인스턴스를 만들어요. 이 메서드는 다중 스레드 접근 목적으로 이 컨텍스트의 새 인스턴스를 만드는 편리한 메서드예요. 예를 들어 여러 스레드가 서로 다른 컨텍스트 요청 제어를 사용하고 싶다면, 각 스레드는 이 메서드를 사용해 이 컨텍스트의 자체 복사본을 얻고 다른 스레드와 동기화할 필요 없이 컨텍스트 요청 제어를 설정/가져올 수 있어요. 새 컨텍스트는 이 컨텍스트와 같은 환경 속성과 연결 요청 제어를 가져요. 자세한 내용은 클래스 설명을 참조하세요. 구현은 그렇게 하는 것이 어느 컨텍스트의 독립성도 방해하지 않는다면 이 컨텍스트와 새 컨텍스트가 같은 네트워크 연결이나 다른 리소스를 공유하도록 허용할 수도 있어요.

Parameters: requestControls - 새 컨텍스트에 사용할, null일 수 있는 요청 제어. null이면 컨텍스트는 요청 제어 없이 초기화돼요
Returns: null이 아닌 LdapContext 인스턴스
Throws: NamingException - 새 인스턴스를 만드는 동안 오류가 발생했을 때
See Also: InitialLdapContext

reconnect

void reconnect(Control[] connCtls)
        throws NamingException

제공된 제어와 이 컨텍스트의 환경을 사용해 LDAP 서버에 다시 연결해요. 이 메서드는 LDAP "bind" 연산을 명시적으로 시작하는 방법이에요. 예를 들어 이 메서드를 사용해 LDAP "bind" 연산에 대한 요청 제어를 설정하거나, 서버에 명시적으로 연결해 LDAP "bind" 연산이 반환한 응답 제어를 얻을 수 있어요. 이 메서드는 이 컨텍스트의 connCtls를 그 새 연결 요청 제어로 설정해요. 이 컨텍스트의 컨텍스트 요청 제어는 영향을 받지 않아요. 이 메서드가 호출된 후의 어떤 암시적 재연결도 connCtls를 사용해 수행될 거예요. connCtls는 이 컨텍스트에서 파생된 새 컨텍스트 인스턴스의 연결 요청 제어로도 사용돼요. 이 연결 요청 제어들은 setRequestControls()의 영향을 받지 않아요. 서비스 공급자 구현자는 구현 세부 내용에 대해 클래스 설명의 "서비스 공급자(Service Provider)" 섹션을 읽어야 해요.

Parameters: connCtls - 사용할, null일 수 있는 제어. null이면 어떤 제어도 사용되지 않아요
Throws: NamingException - 다시 연결하는 동안 오류가 발생했을 때
See Also: getConnectControls(), newInstance(javax.naming.ldap.Control[])

getConnectControls

Control[] getConnectControls()
                      throws NamingException

이 컨텍스트에 적용되는 연결 요청 제어를 가져와요. 제어는 JNDI 구현이 소유하며 불변(immutable)이에요. 배열이나 제어 모두 호출자가 수정해서는 안 돼요.

Returns: null일 수 있는 제어 배열. null은 이 컨텍스트에 연결 제어가 설정되지 않았음을 의미해요
Throws: NamingException - 요청 제어를 가져오는 동안 오류가 발생했을 때

setRequestControls

void setRequestControls(Control[] requestControls)
                 throws NamingException

이후 이 컨텍스트에서 호출되는 메서드에 대한 요청 제어를 설정해요. 요청 제어는 JNDI 구현이 소유하며 불변(immutable)이에요. 배열이나 제어 모두 호출자가 수정해서는 안 돼요. 이것은 이전의 어떤 요청 제어도 제거하고, 이후 이 컨텍스트에서 호출되는 메서드가 사용하도록 requestControls를 추가해요. 이 메서드는 이 컨텍스트의 연결 요청 제어에 영향을 주지 않아요. requestControls는 다음 setRequestControls() 호출까지 적용될 거라는 점에 주의하세요. 그 제어들이 더 이상 컨텍스트 메서드에 영향을 주길 원하지 않으면 null이나 빈 배열로 setRequestControls()를 명시적으로 호출해 제어를 지워야 해요. 이 컨텍스트에 적용되는 요청 제어가 무엇인지 확인하려면 getRequestControls()를 사용해요.

Parameters: requestControls - 사용할, null일 수 있는 제어. null이면 어떤 제어도 사용되지 않아요
Throws: NamingException - 요청 제어를 설정하는 동안 오류가 발생했을 때
See Also: getRequestControls()

getRequestControls

Control[] getRequestControls()
                      throws NamingException

이 컨텍스트에 적용되는 요청 제어를 가져와요. 요청 제어는 JNDI 구현이 소유하며 불변(immutable)이에요. 배열이나 제어 모두 호출자가 수정해서는 안 돼요.

Returns: null일 수 있는 제어 배열. null은 이 컨텍스트에 요청 제어가 설정되지 않았음을 의미해요
Throws: NamingException - 요청 제어를 가져오는 동안 오류가 발생했을 때
See Also: setRequestControls(javax.naming.ldap.Control[])

getResponseControls

Control[] getResponseControls()
                       throws NamingException

이 컨텍스트에서 마지막으로 호출된 메서드의 결과로 생성된 응답 제어를 가져와요. 응답 제어는 JNDI 구현이 소유하며 불변(immutable)이에요. 배열이나 제어 모두 호출자가 수정해서는 안 돼요. 이 응답 제어들은 성공하거나 실패한 연산에 의해 생성되었을 수 있어요. 응답 제어를 반환할 수 있는 컨텍스트 메서드가 호출되면, 이전 메서드 호출의 응답 제어는 지워져요. getResponseControls()는 컨텍스트 메서드가 사용한 LDAP 연산이 생성한 모든 응답 제어를 LDAP 서버로부터 받은 순서대로 반환해요. getResponseControls()를 호출해도 응답 제어는 지워지지 않아요. 제어를 반환할 수 있는 다음 컨텍스트 메서드가 호출될 때까지 이 메서드를 여러 번 호출할 수 있어요(같은 제어를 다시 받음).

Returns: null일 수 있는 제어 배열. null이면 이 컨텍스트에서 이전에 호출된 메서드가 어떤 제어도 생성하지 않았음을 의미해요
Throws: NamingException - 응답 제어를 가져오는 동안 오류가 발생했을 때