From commits-return-11135-apmail-directory-commits-archive=directory.apache.org@directory.apache.org Sun Dec 10 12:48:53 2006 Return-Path: Delivered-To: apmail-directory-commits-archive@www.apache.org Received: (qmail 32663 invoked from network); 10 Dec 2006 12:48:52 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 10 Dec 2006 12:48:51 -0000 Received: (qmail 11955 invoked by uid 500); 10 Dec 2006 12:48:59 -0000 Delivered-To: apmail-directory-commits-archive@directory.apache.org Received: (qmail 11912 invoked by uid 500); 10 Dec 2006 12:48:59 -0000 Mailing-List: contact commits-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@directory.apache.org Delivered-To: mailing list commits@directory.apache.org Received: (qmail 11901 invoked by uid 99); 10 Dec 2006 12:48:59 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 10 Dec 2006 04:48:59 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 10 Dec 2006 04:48:51 -0800 Received: by eris.apache.org (Postfix, from userid 65534) id 711291A9846; Sun, 10 Dec 2006 04:48:07 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r485169 - in /directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation: Operation.java OperationFactory.java Date: Sun, 10 Dec 2006 12:48:07 -0000 To: commits@directory.apache.org From: trustin@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20061210124807.711291A9846@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: trustin Date: Sun Dec 10 04:48:06 2006 New Revision: 485169 URL: http://svn.apache.org/viewvc?view=rev&rev=485169 Log: * Added JavaDoc for OperationFactory * Fixed a subtle error in Operation JavaDoc Modified: directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/Operation.java directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/OperationFactory.java Modified: directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/Operation.java URL: http://svn.apache.org/viewvc/directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/Operation.java?view=diff&rev=485169&r1=485168&r2=485169 ============================================================================== --- directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/Operation.java (original) +++ directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/Operation.java Sun Dec 10 04:48:06 2006 @@ -41,7 +41,7 @@ *

* An {@link Operation} is usually created by calling factory methods in * {@link OperationFactory}, which produces a {@link CompositeOperation} of - * smaller multiple operation. For example, + * smaller multiple operations. For example, * {@link OperationFactory#newDelete(LdapDN)} returns a * {@link CompositeOperation} which consists of two * {@link ReplaceAttributeOperation}s; one updates {@link Constants#ENTRY_CSN} Modified: directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/OperationFactory.java URL: http://svn.apache.org/viewvc/directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/OperationFactory.java?view=diff&rev=485169&r1=485168&r2=485169 ============================================================================== --- directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/OperationFactory.java (original) +++ directory/trunks/apacheds/mitosis/src/main/java/org/apache/directory/mitosis/operation/OperationFactory.java Sun Dec 10 04:48:06 2006 @@ -48,8 +48,27 @@ /** - * Converts a complex JNDI operations into multiple simple operations. - * + * Creates an {@link Operation} instance for a JNDI operation. The + * {@link Operation} instance returned by the provided factory methods are + * mostly a {@link CompositeOperation}, which consists smaller JNDI + * operations. The elements of the {@link CompositeOperation} differs between + * the original JNDI operation to make the operation more robust to + * replication conflict. All {@link Operation}s created by + * {@link OperationFactory} whould be robust to the replication conflict and + * should be able to recover from the conflict. + *

+ * "Add" (or "bind") is the only operation that doesn't return a + * {@link CompositeOperation} but returns an {@link AddEntryOperation}. + * It is because all other operations needs to update its related entry's + * {@link Constants#ENTRY_CSN} or {@link Constants#ENTRY_DELETED} attribute + * with additional sub-operations. In contrast, "add" operation doesn't need + * to create a {@link CompositeOperation} because those attributes can be + * added just modifying an {@link AddEntryOperation} rather than creating + * a parent operation and add sub-operations there. + *

+ * Please note that all operations update {@link Constants#ENTRY_CSN} and + * documentation for each method won't explain this behavior. + * * @author Apache Directory Project */ public class OperationFactory @@ -71,12 +90,22 @@ } + /** + * Creates a new {@link Operation} that performs LDAP "add" operation + * with a newly generated {@link CSN}. + */ public Operation newAdd( LdapDN normalizedName, Attributes entry ) throws NamingException { return newAdd( newCSN(), normalizedName, entry ); } + /** + * Creates a new {@link Operation} that performs LDAP "add" operation + * with the specified {@link CSN}. The new entry will have three + * additional attributes; {@link Constants#ENTRY_CSN} ({@link CSN}), + * {@link Constants#ENTRY_UUID}, and {@link Constants#ENTRY_DELETED}. + */ private Operation newAdd( CSN csn, LdapDN normalizedName, Attributes entry ) throws NamingException { // Check an entry already exists. @@ -98,6 +127,11 @@ } + /** + * Creates a new {@link Operation} that performs "delete" operation. + * The created {@link Operation} doesn't actually delete the entry. + * Instead, it sets {@link Constants#ENTRY_DELETED} to "true". + */ public Operation newDelete( LdapDN normalizedName ) { CSN csn = newCSN(); @@ -111,6 +145,14 @@ } + /** + * Returns a new {@link Operation} that performs "modify" operation. + * + * @return a {@link CompositeOperation} that consists of one or more + * {@link AttributeOperation}s and one additional operation that + * sets {@link Constants#ENTRY_DELETED} to "false" to resurrect the + * entry the modified attributes belong to. + */ public Operation newModify( LdapDN normalizedName, int modOp, Attributes attributes ) { CSN csn = newCSN(); @@ -131,6 +173,14 @@ } + /** + * Returns a new {@link Operation} that performs "modify" operation. + * + * @return a {@link CompositeOperation} that consists of one or more + * {@link AttributeOperation}s and one additional operation that + * sets {@link Constants#ENTRY_DELETED} to "false" to resurrect the + * entry the modified attributes belong to. + */ public Operation newModify( LdapDN normalizedName, ModificationItem[] items ) { CSN csn = newCSN(); @@ -151,6 +201,12 @@ } + /** + * Returns a new {@link AttributeOperation} that performs one + * attribute modification operation. This method is called by other + * methods internally to create an appropriate {@link AttributeOperation} + * instance from the specified modOp value. + */ private Operation newModify( CSN csn, LdapDN normalizedName, int modOp, Attribute attribute ) { switch ( modOp ) @@ -167,6 +223,13 @@ } + /** + * Returns a new {@link Operation} that performs "modifyRN" operation. + * This operation is a subset of "move" operation. + * Calling this method actually forwards the call to + * {@link #newMove(LdapDN, LdapDN, String, boolean)} with unchanged + * newParentName. + */ public Operation newModifyRn( LdapDN oldName, String newRdn, boolean deleteOldRn ) throws NamingException { LdapDN newParentName = ( LdapDN ) oldName.clone(); @@ -176,12 +239,25 @@ } + /** + * Returns a new {@link Operation} that performs "move" operation. + * Calling this method actually forwards the call to + * {@link #newMove(LdapDN, LdapDN, String, boolean)} with unchanged + * newRdn and 'true' deleteOldRn. + */ public Operation newMove( LdapDN oldName, LdapDN newParentName ) throws NamingException { return newMove( oldName, newParentName, oldName.get( oldName.size() - 1 ), true ); } + /** + * Returns a new {@link Operation} that performs "move" operation. + * Please note this operation is the most fragile operation I've written + * so it should be reviewed completely again. This methods + * doesn't allow you to specify deleteOldRn as false + * for now. This limitation should be removed too. + */ public Operation newMove( LdapDN oldName, LdapDN newParentName, String newRdn, boolean deleteOldRn ) throws NamingException { @@ -239,6 +315,11 @@ } + /** + * Make sure the specified newEntryName already exists. It + * checked {@link Constants#ENTRY_DELETED} additionally to see if the + * entry actually exists in a {@link Partition} but maked as deleted. + */ private void checkBeforeAdd( LdapDN newEntryName ) throws NamingException { if ( nexus.hasEntry( newEntryName ) ) @@ -262,6 +343,12 @@ } + /** + * Adds default {@link Operation}s that should be followed by all + * JNDI/LDAP operations except "add/bind" operation. This method + * currently adds only one attribute, {@link Constants#ENTRY_CSN}. + * @return what you specified as a parameter to enable invocation chaining + */ private CompositeOperation addDefaultOperations( CompositeOperation result, CSN csn, LdapDN normalizedName ) { result.add( new ReplaceAttributeOperation( csn, normalizedName, new BasicAttribute( Constants.ENTRY_CSN, csn @@ -269,7 +356,10 @@ return result; } - + /** + * Creates new {@link CSN} from the {@link CSNFactory} which was specified + * in the constructor. + */ private CSN newCSN() { return csnFactory.newInstance( replicaId );