[jboss-cvs] JBossAS SVN: r57639 - projects/cluster/trunk/ha-client/src/main/java/org/jboss/ha/client
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Oct 12 23:25:22 EDT 2006
Author: bstansberry at jboss.com
Date: 2006-10-12 23:25:21 -0400 (Thu, 12 Oct 2006)
New Revision: 57639
Modified:
projects/cluster/trunk/ha-client/src/main/java/org/jboss/ha/client/FamilyClusterInfo.java
Log:
Fix license and package; add javadoc
Modified: projects/cluster/trunk/ha-client/src/main/java/org/jboss/ha/client/FamilyClusterInfo.java
===================================================================
--- projects/cluster/trunk/ha-client/src/main/java/org/jboss/ha/client/FamilyClusterInfo.java 2006-10-13 03:24:57 UTC (rev 57638)
+++ projects/cluster/trunk/ha-client/src/main/java/org/jboss/ha/client/FamilyClusterInfo.java 2006-10-13 03:25:21 UTC (rev 57639)
@@ -1,53 +1,45 @@
/*
- * JBoss, Home of Professional Open Source
- * Copyright 2005, JBoss Inc., and individual contributors as indicated
- * by the @authors tag. See the copyright.txt in the distribution for a
- * full listing of individual contributors.
- *
- * This is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation; either version 2.1 of
- * the License, or (at your option) any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this software; if not, write to the Free
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
- */
-package org.jboss.ha.framework.interfaces;
+ * JBoss, a division of Red Hat
+ * Copyright 2006, Red Hat Middleware, LLC, and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.ha.client;
import java.util.List;
/**
- * Maintain information for a given proxy family. Proxies can statically reference
- * objects implementing this interface: only the content will change as the
- * cluster topology changes, not the FamilyClusterInfo object itself.
- * Proxies or LoadBalancing policy implementations can use the cursor and object
- * attribute to store arbitrary data that is then shared accross all proxies belonging
- * to the same family.
- * Initial access to this object is done through the ClusteringTargetsRepository singleton.
- *
- * @see org.jboss.ha.framework.interfaces.FamilyClusterInfoImpl
- * @see org.jboss.ha.framework.interfaces.ClusteringTargetsRepository
- *
- * @author <a href="mailto:sacha.labourey at cogito-info.ch">Sacha Labourey</a>.
- * @version $Revision$
- *
- * <p><b>Revisions:</b>
- *
- * <p><b>2002/08/23, Sacha Labourey:</b>
- * <ul>
- * <li> First implementation </li>
- * </ul>
+ * Maintain information for a given proxy family. Proxies can statically reference objects implementing this interface: only the content will change as the cluster topology changes, not the FamilyClusterInfo object itself. Proxies or LoadBalancePolicy implementations can use the cursor and object attribute to store arbitrary data that is then shared accross all proxies belonging to the same family. Initial access to this object is done through the ClusteringTargetsRepository singleton.
+ * @see org.jboss.ha.client.FamilyClusterInfoImpl
+ * @see org.jboss.ha.client.ClusteringTargetsRepository
+ * @author <a href="mailto:sacha.labourey at cogito-info.ch">Sacha Labourey</a>.
+ * @author brian.stansberry at jboss.com
+ * @version $Revision$ <p><b>Revisions:</b> <p><b>2002/08/23, Sacha Labourey:</b> <ul> <li> First implementation </li> </ul>
*/
public interface FamilyClusterInfo
{
+ /** Value returned by {@link #getCursor()} to indicate no cursor has been set */
+ public final static int UNINITIALIZED_CURSOR = 999999999;
+
+ /**
+ * Gets the name of the proxy family.
+ */
public String getFamilyName ();
/**
@@ -55,18 +47,30 @@
*
* <strong>NOTE:</strong> Implementations should synchronize on themselves
* when executing this method (see JBAS-2071).
+ *
+ * @return an unmodifiable view of the target list
*/
public List getTargets ();
+
+ /**
+ * Gets a hash of the cluster topology for this family.
+ * This value can be passed back to the server as a shorthand for
+ * the current client-side view of the cluster, allowing the server
+ * to provide a new list of targets if the client is out of sync
+ * with the current topology.
+ */
public long getCurrentViewId ();
/**
- * Remove the given target from the list of targets.
+ * Remove the given target from the list of targets. Does not
+ * update the view id.
*
* <strong>NOTE:</strong> Implementations should synchronize on themselves
* when executing this method (see JBAS-2071).
*
- * @param target the target
- * @return the updated list of targets
+ * @param target the target to remove
+ *
+ * @return an unmodifiable view of the updated target list
*/
public List removeDeadTarget(Object target);
@@ -75,9 +79,17 @@
*
* <strong>NOTE:</strong> Implementations should synchronize on themselves
* when executing this method (see JBAS-2071).
+ *
+ * @return an unmodifiable view of the updated target list
*/
public List updateClusterInfo (List targets, long viewId);
+ /**
+ * Gets whether the current view id is in sync with the current list of
+ * targets. Will be <code>false</code> if {@link #removeDeadTarget} or
+ * {@link #resetView()} has been called since the last call to
+ * {@link #updateClusterInfo(List, long)}.
+ */
public boolean currentMembershipInSyncWithViewId();
/**
@@ -88,15 +100,34 @@
*/
public void resetView ();
- // arbitrary usage by the LoadBalancePolicy implementation
- // We could have used an HashMap but the lookup would have taken
- // much more time and we probably don't need as much flexibility
- // (+ it is slow for a simple int)
- //
+ /**
+ * Gets the index of the current cursor in the list of targets, if any. <p> For use by {@link LoadBalancePolicy} implementations like {@link RoundRobin} that sequentially move through the list of targets. Storing the index in the FamilyClusterInfo allows multiple LoadBalancePolicy instances to coordinate their target selections. </p> <p> This information could also be stored in a static map in RoundRobin, but the map lookup would be slower. </p>
+ * @return the current cursor or {@link #UNINITIALIZED_CURSOR} if there is no valid cursor.
+ * @uml.property name="cursor"
+ */
public int getCursor();
+
+ /**
+ * Sets the index of the current cursor in the list of targets, if any.
+ * @param cursor the new cursor position
+ * @return the cursor position after this call
+ * @see #getCursor()
+ * @uml.property name="cursor"
+ */
public int setCursor (int cursor);
+
+ /**
+ * Gets an object arbitrarily cached in this object. The expected use is that one of the targets in the list of targets would be stored by a {@link LoadBalancePolicy} implementation like {@link FirstAvailableIdenticalAllProxies} . Storing the target in the FamilyClusterInfo allows multiple LoadBalancePolicy instances to ensure they use the same target. <p> This information could also be stored in a static map in FirstAvailableIdenticalAllProxies, but the map lookup would be slower. </p>
+ * @return whatever was last passed to {@link #setObject(Object)} , or <code>null</code> if nothing was.
+ * @uml.property name="object"
+ */
public Object getObject ();
+
+ /**
+ * Sets an arbitrary object for caching in this object. The expected use is that one of the targets in the list of targets would be stored by a {@link LoadBalancePolicy} implementation like {@link FirstAvailableIdenticalAllProxies} . Storing the target in the FamilyClusterInfo allows multiple LoadBalancePolicy instances to ensure they use the same target.
+ * @param whatever the object to cache
+ * @return the object that is now cached.
+ * @uml.property name="object"
+ */
public Object setObject (Object whatever);
-
- public final static int UNINITIALIZED_CURSOR = 999999999;
}
More information about the jboss-cvs-commits
mailing list