패키지 javax.naming.ldap

LDAPv3 의 확장 조작과 컨트롤을 서포트합니다.

참조:
설명

인터페이스의 개요

Control	이 인터페이스는 「RFC 2251」으로 정의되고 있게 LDAPv3 컨트롤을 표시합니다.
ExtendedRequest	이 인터페이스는 「RFC 2251」으로 정의되고 있는 LDAPv3 확장 조작의 요구를 나타냅니다.
ExtendedResponse	이 인터페이스는 「RFC 2251」으로 정의되고 있는 LDAP 확장 조작의 응답을 나타냅니다.
HasControls	이 인터페이스는 오브젝트가 NamingEnumerations 로 돌려주어질 때, 컨트롤을 돌려주는데 사용됩니다.
LdapContext	이 인터페이스는 LDAPv3 스타일의 컨트롤을 가지는 조작과 LDAPv3 스타일의 확장 조작을 실행할 수 있는 문맥을 나타냅니다.
UnsolicitedNotification	이 인터페이스는 「RFC 2251」으로 정의된 비요청 통지를 나타냅니다.
UnsolicitedNotificationListener	이 인터페이스는 UnsolicitedNotificationEvent 를 처리하기 위한의 것입니다.

클래스의 개요

ControlFactory	이 추상 클래스는 LDAPv3 컨트롤의 작성에 사용하는 팩토리를 표시합니다.
InitialLdapContext	이 클래스는 LDAPv3 스타일의 확장 조작 및 확장 컨트롤을 실행하기 위한 개시 문맥입니다.
StartTlsRequest	이 클래스는 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security 에 정의되고 있는 LDAPv3 의 StartTLS 확장 요구를 구현합니다.
StartTlsResponse	이 클래스는 Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security 에 정의되고 있는 LDAPv3 의 StartTLS 확장 응답을 구현합니다.
UnsolicitedNotificationEvent	이 클래스는 LDAP 서버로부터 송신된 비요청 통지에 응해 방아쇠 된 이벤트를 나타냅니다.

예외의 개요

LdapReferralException

이 abstract 클래스는 LDAP 참조 예외를 나타내기 위해서(때문에) 사용됩니다.

패키지 javax.naming.ldap 의 설명

LDAPv3 의 확장 조작과 컨트롤을 서포트합니다.

이 패키지는 Java Naming and Directory Interface^TM (JNDI)의 디렉토리 조작을 확장합니다. JNDI 는 Java 프로그램 언어로 작성된 어플리케이션에 네이밍 기능 및 디렉토리 기능을 제공합니다. JNDI 는 특정의 네이밍 또는 디렉토리 서비스 구현과는 독립해 설계되고 있습니다. 이 때문에, 새로운 서비스 및 벌써 배치되고 있는 여러가지 서비스에, 공통의 방법으로 액세스 할 수 있습니다.

이 패키지는 「RFC 2251」으로 정의된 LDAPv3 의 확장 조작과 컨트롤을 처리하는 어플리케이션 및 서비스 프로바이더전용의 것입니다. 이 패키지의 코어 인터페이스는 LdapContext 로, 이것은 확장 조작 실행 및 컨트롤 처리의 문맥의 메소드를 정의합니다.

확장 조작

이 패키지는 확장 조작의 인수를 나타내는 ExtendedRequest 인터페이스 및 확장 조작의 결과를 나타내는 ExtendedResponse 인터페이스를 정의합니다. 확장 응답은 항상 확장 요구와 페어가 됩니다만, 확장 요구는 반드시 확장 응답과 페어가 될 필요는 없습니다. 즉, 대응하는 확장 응답이 없는 확장 요구를 가질 수 있다고 하는 것입니다.

어플리케이션은 통상, 이러한 인터페이스를 직접은 처리하지 않습니다. 대신에, 이러한 인터페이스를구현하고 있는클래스를 처리합니다. 어플리케이션은 이러한 클래스를, IETF 에 의해 표준화 된 확장 조작으로서 취득하든가, 혹은 벤더 고유의 확장 조작의 디렉토리 벤더로부터 취득합니다. 요구 클래스에는 형태 프로텍션된 유저가 사용하기 쉬운 방법으로 인수를 받아들이는 constructor 이 필요해, 응답 클래스에는 형태 프로텍션된 유저가 사용하기 쉬운 방법으로 응답의 데이터를 취득하기 위한 액세스 메소드가 필요합니다. 내부적으로는 요구 클래스 및 응답 클래스는 BER 치의 encode 및 복호화(decode)를 처리합니다.

예를 들어, LDAP 서버가 「시간 취득」의 확장 조작을 서포트하고 있는 경우, LDAP 서버는 어플리케이션이 이 기능을 사용할 수 있도록,GetTimeRequest 나 GetTimeResponse 등의 클래스를 지정합니다. 어플리케이션은 이러한 기능을 다음과 같이 사용합니다.

GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();

GetTimeRequest 및 GetTimeResponse 클래스는 다음과 같이 정의할 수 있습니다.

public class GetTimeRequest implements ExtendedRequest {
    // User-friendly constructor 
    public GetTimeRequest() {
    };

    // Methods used by service providers
    public String getID() {
        return GETTIME_REQ_OID;
    }
    public byte[] getEncodedValue() {
        return null;  // no value needed for get time request
    }
    public ExtendedResponse createExtendedResponse(
        String id, byte[] berValue, int offset, int length) throws NamingException {
        return new GetTimeResponse(id, berValue, offset, length);
    }
}
public class GetTimeResponse() implements ExtendedResponse {
    long time;
    // called by GetTimeRequest.createExtendedResponse()
    public GetTimeResponse(String id, byte[] berValue, int offset, int length) 
        throws NamingException {
        // check validity of id
        long time =  ... // decode berValue to get time
    }

    // Type-safe and User-friendly methods
    public java.util.Date getDate() { return new java.util.Date(time); }
    public long getTime() { return time; }

    // Low level methods
    public byte[] getEncodedValue() {
        return // berValue saved;
    }
    public String getID() {
        return GETTIME_RESP_OID;
    }
}

컨트롤

이 패키지는 LDAPv3 컨트롤을 나타내는 Control 인터페이스를 정의합니다. 이 인터페이스는 LDAP 서버에 송신되는 컨트롤 (요구 컨트롤)이 되든가, 혹은 LDAP 서버에 의해 돌려주어지는 컨트롤 (응답 컨트롤)이 됩니다. 확장 요구나 확장 응답과 달리, 반드시 요구 컨트롤과 응답 컨트롤의 사이에 페어를 짤 필요는 없습니다. 요구 컨트롤을 송신해 응답 컨트롤이 돌아오지 않게 하거나 혹은 요구 컨트롤을 송신하지 않고 응답 컨트롤을 수신하거나 할 수 있습니다.

어플리케이션은 통상, 이 인터페이스를 직접은 처리하지 않습니다. 대신에, 이 인터페이스를구현하고 있는클래스를 처리합니다. 어플리케이션은 컨트롤 클래스를, 표준화 된 컨트롤의 repertoire의 일부로서 IETF 로부터 취득하든가, 혹은 벤더 고유 컨트롤의 디렉토리 벤더로부터 취득합니다. 요구 컨트롤 클래스에는 형태 프로텍션된 유저가 사용하기 쉬운 방법으로 인수를 받는 constructor 이 필요해, 응답 컨트롤 클래스에는 형태 프로텍션된 유저가 사용하기 쉬운 방법으로 응답의 데이터를 취득하기 위한 액세스 메소드가 필요합니다. 내부적으로는 요구 컨트롤 클래스 및 응답 컨트롤 클래스는 BER 치의 encode 및 복호화(decode)를 취급합니다.

예를 들어, LDAP 서버가 「소트」의 요구 컨트롤을 서포트하고 있는 경우, 이 컨트롤은 검색 요구와 함께 송신되었을 경우, 검색 결과를 특정의 속성으로 순서 붙여 돌려주도록(듯이) 서버에 요구합니다. 이 컨트롤은 어플리케이션이 이 기능을 사용할 수 있도록,SortControl 클래스를 지정합니다. 어플리케이션은 이 클래스를 다음과 같이 사용합니다.

Control[] reqCtls = new Control[] {new SortControl("age")};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);

SortControl 클래스는 다음과 같이 정의할 수 있습니다.

public class SortControl implements Control {
    // User-friendly constructor 
    public SortControl(String attrID) {
        // encode attrID
    };

    // Methods used by service providers
    public String getID() {
        return SORT_OID;
    }
    public byte[] getEncodedValue() {
        return // encoded attrID
    }
    ...
}

서비스 프로바이더가 응답 컨트롤을 수신하면(자), 이 프로바이더는 ControlFactory 클래스를 사용해,Control 인터페이스를 구현하는 특정의 클래스를 생성합니다.

LDAP 서버는 LDAP 조작과 함께 응답 컨트롤을 답신할 수 있어 또 리스트나 검색 조작등에 의해 돌려주어진 열거 결과와 함께 답장할 수 있겠습니다. LdapContext 는 LDAP 조작과 함께 송신된 응답 컨트롤을 취득하는 메소드 (getResponseControls())를 제공해,HasControls 는 열거 결과에 관련한 응답 컨트롤을 취득하는데 사용됩니다.

예를 들어, 변경 완료에 따라 LDAP 서버가 「ID 변경」컨트롤을 답장하는 경우, 서버는 어플리케이션이 이 기능을 사용할 수 있게 ChangeIDControl 클래스를 지정합니다. 어플리케이션은 갱신을 실시해, 계속되어 ID 변경을 취득하려고 합니다.

// Perform update
Context ctx = ectx.createSubsubcontext("cn=newobj");

// Get response controls
Control[] respCtls = ectx.getResponseControls();
if (respCtls ! = null) {
    // Find the one we want
    for (int i = 0; i < respCtls; i++) {
        if(respCtls[i] instanceof ChangeIDControl) {
	    ChangeIDControl cctl = (ChangeIDControl) respCtls[i];
	    System.out.println(cctl.getChangeID());
        }
    }
}

벤더는 다음과 같은 ChangeIDControl 클래스 및 VendorXControlFactory 클래스를 지정합니다. VendorXControlFactory 는 서비스 프로바이더가 LDAP 서버로부터 응답 컨트롤을 수신했을 때에 그 프로바이더가 사용합니다.

public class ChangeIDControl implements Control {
    long id;

    // Constructor used by ControlFactory
    public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
        // check validity of OID
        id = // extract change ID from berVal
    };

    // Type-safe and User-friendly method
    public long getChangeID() {
        return id;
    }

    // Low-level methods
    public String getID() {
        return CHANGEID_OID;
    }
    public byte[] getEncodedValue() {
        return // original berVal
    }
    ...
}
public class VendorXControlFactory extends ControlFactory {
    public VendorXControlFactory () {
    }

    public Control getControlInstance(Control orig) throws NamingException {
        if (isOneOfMyControls(orig.getID())) {
	    ... 

	    // determine which of ours it is and call its constructor
	    return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
	}
        return null;  // not one of ours
    }
}

패키지의 사양

「Java technology web site」에서는 다음의 문서를 참조할 수 있습니다.

• 「JNDI API Document」 (Postscript)
• 「JNDI API Document」 (PDF)

도입된 버젼:

1.3