Author: elecharny
Date: Fri Apr  3 12:16:37 2009
New Revision: 761646

URL: http://svn.apache.org/viewvc?rev=761646&view=rev
Log:
o Added the SearchXXX interfaces
o Added the Referral interface

Added:
    directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/Referral.java
    directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchDoneResponse.java
    directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchEntryResponse.java
    directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchReferenceResponse.java
Modified:
    directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResult.java
    directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResultImpl.java

Modified: directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResult.java
URL: http://svn.apache.org/viewvc/directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResult.java?rev=761646&r1=761645&r2=761646&view=diff
==============================================================================
--- directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResult.java (original)
+++ directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResult.java Fri Apr  3 12:16:37 2009
@@ -20,7 +20,7 @@
 
 package org.apache.directory.shared.ldap.client.api.messages;
 
-import org.apache.directory.shared.ldap.message.Referral;
+import org.apache.directory.shared.ldap.message.InternalReferral;
 import org.apache.directory.shared.ldap.message.ResultCodeEnum;
 import org.apache.directory.shared.ldap.name.LdapDN;
 
@@ -124,7 +124,7 @@
      * 
      * @return the referral on REFERRAL errors, null on all others.
      */
-    Referral getReferral();
+    InternalReferral getReferral();
 
 
     /**
@@ -136,5 +136,5 @@
      * @param referral
      *            optional referral on REFERRAL errors.
      */
-    void setReferral( Referral referral );
+    void setReferral( InternalReferral referral );
 }

Modified: directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResultImpl.java
URL: http://svn.apache.org/viewvc/directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResultImpl.java?rev=761646&r1=761645&r2=761646&view=diff
==============================================================================
--- directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResultImpl.java (original)
+++ directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/LdapResultImpl.java Fri Apr  3 12:16:37 2009
@@ -20,7 +20,7 @@
 
 package org.apache.directory.shared.ldap.client.api.messages;
 
-import org.apache.directory.shared.ldap.message.Referral;
+import org.apache.directory.shared.ldap.message.InternalReferral;
 import org.apache.directory.shared.ldap.message.ResultCodeEnum;
 import org.apache.directory.shared.ldap.name.LdapDN;
 
@@ -37,7 +37,7 @@
     private LdapDN matchedDn;
 
     /** Referral associated with this LdapResult if the errorCode is REFERRAL */
-    private Referral referral;
+    private InternalReferral referral;
 
     /** Decriptive error message - defaults to empty string */
     private String errorMessage;
@@ -140,7 +140,7 @@
      * 
      * @return the referral on REFERRAL errors, null on all others.
      */
-    public Referral getReferral()
+    public InternalReferral getReferral()
     {
         return referral;
     }
@@ -167,7 +167,7 @@
      * @param referral
      *            optional referral on REFERRAL errors.
      */
-    public void setReferral( Referral referral )
+    public void setReferral( InternalReferral referral )
     {
         this.referral = referral;
     }

Added: directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/Referral.java
URL: http://svn.apache.org/viewvc/directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/Referral.java?rev=761646&view=auto
==============================================================================
--- directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/Referral.java (added)
+++ directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/Referral.java Fri Apr  3 12:16:37 2009
@@ -0,0 +1,131 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *  
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *  
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License. 
+ *  
+ */
+package org.apache.directory.shared.ldap.client.api.messages;
+
+
+import java.util.Collection;
+
+import org.apache.directory.shared.ldap.util.LdapURL;
+
+
+/**
+ * Represents a referral which is a set of alternative locations where an entry
+ * can be found. Here's what <a href="http://www.faqs.org/rfcs/rfc2251.html">
+ * RFC 2251 </a> has to say about it:
+ * 
+ * <pre>
+ *  4.1.11. Referral
+ * 
+ *   The referral error indicates that the contacted server does not hold
+ *   the target entry of the request.  The referral field is present in an
+ *   LDAPResult if the LDAPResult.resultCode field value is referral, and
+ *   absent with all other result codes.  It contains a reference to
+ *   another server (or set of servers) which may be accessed via LDAP or
+ *   other protocols.  Referrals can be returned in response to any
+ *   operation request (except unbind and abandon which do not have
+ *   responses). At least one URL MUST be present in the Referral.
+ * 
+ *   The referral is not returned for a singleLevel or wholeSubtree search
+ *   in which the search scope spans multiple naming contexts, and several
+ *   different servers would need to be contacted to complete the
+ *   operation. Instead, continuation references, described in section
+ *   4.5.3, are returned.
+ * 
+ *        Referral ::= SEQUENCE OF LDAPURL  -- one or more
+ * 
+ *        LDAPURL ::= LDAPString -- limited to characters permitted in URLs
+ * 
+ *   If the client wishes to progress the operation, it MUST follow the
+ *   referral by contacting any one of servers.  All the URLs MUST be
+ *   equally capable of being used to progress the operation.  (The
+ *   mechanisms for how this is achieved by multiple servers are outside
+ *   the scope of this document.)
+ * 
+ *   URLs for servers implementing the LDAP protocol are written according
+ *   to &lt;a href=&quot;http://www.faqs.org/rfcs/rfc2255.html&quot;&gt;[9]&lt;/a&gt;.  If an alias
+ *   was dereferenced, the &lt;dn&gt; part of the URL MUST be present, with the new
+ *   target object name.  If the &lt;dn&gt; part is present, the client MUST use this
+ *   name in its next request to progress the operation, and if it is not present
+ *   the client will use the same name as in the original request.  Some servers
+ *   (e.g. participating in distributed indexing) may provide a different filter
+ *   in a referral for a search operation.  If the filter part of the URL
+ *    is present in an LDAPURL, the client MUST use this filter in its next
+ *   request to progress this search, and if it is not present the client
+ *   MUST use the same filter as it used for that search.  Other aspects
+ *   of the new request may be the same or different as the request which
+ *   generated the referral.
+ * 
+ *   Note that UTF-8 characters appearing in a DN or search filter may not
+ *   be legal for URLs (e.g. spaces) and MUST be escaped using the %
+ *   method in RFC 1738 &lt;a href=&quot;http://www.faqs.org/rfcs/rfc1738.html&quot;&gt;[7]&lt;/a&gt;.
+ * 
+ *   Other kinds of URLs may be returned, so long as the operation could
+ *   be performed using that protocol.
+ * </pre>
+ * 
+ * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
+ * @version $Rev: 761643 $
+ * TODO This interface should be located in a url package under common to be
+ *       constructed from a LDAPv3 URL parser. The interface will eventually
+ *       look very different once url support is added: for one it will add and
+ *       remove LdapUrl objects instead of strings or provide both string and
+ *       LdapUrl add/remove methods.
+ */
+public interface Referral
+{
+    /**
+     * Gets an unmodifiable set of alternative referral urls.
+     * 
+     * @return the alternative url objects.
+     */
+    Collection<String> getLdapUrls();
+
+
+    /**
+     * Adds an LDAPv3 URL to this Referral.
+     * 
+     * @param urls the LDAPv3 URLs to add
+     */
+    void addLdapUrls( String... urls );
+
+
+    /**
+     * Adds an LDAPv3 URL to this Referral.
+     * 
+     * @param urls the LDAPv3 URLs to add
+     */
+    void addLdapUrls( LdapURL... urls );
+
+
+    /**
+     * Removes an LDAPv3 URL to this Referral.
+     * 
+     * @param urls the LDAPv3 URLs to remove
+     */
+    void removeLdapUrl( String... urls );
+
+
+    /**
+     * Removes an LDAPv3 URL to this Referral.
+     * 
+     * @param urls the LDAPv3 URLs to remove
+     */
+    void removeLdapUrl( LdapURL... urls );
+}

Added: directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchDoneResponse.java
URL: http://svn.apache.org/viewvc/directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchDoneResponse.java?rev=761646&view=auto
==============================================================================
--- directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchDoneResponse.java (added)
+++ directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchDoneResponse.java Fri Apr  3 12:16:37 2009
@@ -0,0 +1,31 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *  
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *  
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License. 
+ *  
+ */
+package org.apache.directory.shared.ldap.client.api.messages;
+
+
+/**
+ * Search done protocol response message used to indicate the completion of a
+ * search request message.
+ * 
+ * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
+ */
+public interface SearchDoneResponse extends ResponseWithResult
+{
+}

Added: directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchEntryResponse.java
URL: http://svn.apache.org/viewvc/directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchEntryResponse.java?rev=761646&view=auto
==============================================================================
--- directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchEntryResponse.java (added)
+++ directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchEntryResponse.java Fri Apr  3 12:16:37 2009
@@ -0,0 +1,59 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *  
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *  
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License. 
+ *  
+ */
+
+package org.apache.directory.shared.ldap.client.api.messages;
+
+
+import org.apache.directory.shared.ldap.entry.Entry;
+import org.apache.directory.shared.ldap.name.LdapDN;
+
+
+/**
+ * Search entry protocol response message used to return non referral entries to
+ * the client in response to a search request message.
+ * 
+ * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+ * @version $Revision: 760984 $
+ */
+public interface SearchEntryResponse extends SearchResponse
+{
+    /**
+     * Gets the distinguished name of the entry object returned.
+     * 
+     * @return the Dn of the entry returned.
+     */
+    LdapDN getObjectName();
+
+
+    /**
+     * Gets the entry.
+     * 
+     * @return the entry
+     */
+    Entry getEntry();
+
+
+    /**
+     * Sets an entry
+     * 
+     * @param entry the entry
+     */
+    void setEntry( Entry entry );
+}

Added: directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchReferenceResponse.java
URL: http://svn.apache.org/viewvc/directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchReferenceResponse.java?rev=761646&view=auto
==============================================================================
--- directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchReferenceResponse.java (added)
+++ directory/shared/branches/shared-replication/client-api/src/main/java/org/apache/directory/shared/ldap/client/api/messages/SearchReferenceResponse.java Fri Apr  3 12:16:37 2009
@@ -0,0 +1,81 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *  
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *  
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License. 
+ *  
+ */
+
+package org.apache.directory.shared.ldap.client.api.messages;
+
+import org.apache.directory.shared.ldap.util.LdapURL;
+
+
+/**
+ * Search reference protocol response message used to return referrals to the
+ * client in response to a search request message.
+ * 
+ * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
+ * @version $Revision: 760984 $
+ */
+public interface SearchReferenceResponse extends SearchResponse
+{
+    /**
+     * Gets the sequence of LdapUrls as a Referral instance.
+     * 
+     * @return the sequence of LdapUrls
+     */
+    Referral getReferrals();
+
+
+    /**
+     * Sets the sequence of LdapUrls as a Referral instance.
+     * 
+     * @param referrals the sequence of LdapUrls
+     */
+    void setReferral( Referral referrals );
+
+
+    /**
+     * Sets the sequence of LdapUrls as a Referral instance.
+     * 
+     * @param referrals the sequence of LdapUrls
+     */
+    void addReferrals( LdapURL... referrals );
+
+
+    /**
+     * Sets the sequence of LdapUrls as a Referral instance.
+     * 
+     * @param referrals the sequence of LdapUrls
+     */
+    void addReferrals( String... referrals );
+
+
+    /**
+     * Removes the sequence of LdapUrls from the Referral instance.
+     * 
+     * @param referrals the sequence of LdapUrls
+     */
+    void removeReferrals( LdapURL... referrals );
+
+
+    /**
+     * Removes the sequence of LdapUrls from the Referral instance.
+     * 
+     * @param referrals the sequence of LdapUrls
+     */
+    void removeReferrals( String... referrals );
+}