Author: stefanegli
Date: Tue Apr 23 09:37:15 2013
New Revision: 1470861
URL: http://svn.apache.org/r1470861
Log:
SLING-2827 : javadoc of Type clarified - plus a source code reformat
Modified:
sling/trunk/contrib/extensions/discovery/api/src/main/java/org/apache/sling/discovery/TopologyEvent.java
Modified:
sling/trunk/contrib/extensions/discovery/api/src/main/java/org/apache/sling/discovery/TopologyEvent.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/extensions/discovery/api/src/main/java/org/apache/sling/discovery/TopologyEvent.java?rev=1470861&r1=1470860&r2=1470861&view=diff
==============================================================================
---
sling/trunk/contrib/extensions/discovery/api/src/main/java/org/apache/sling/discovery/TopologyEvent.java
(original)
+++
sling/trunk/contrib/extensions/discovery/api/src/main/java/org/apache/sling/discovery/TopologyEvent.java
Tue Apr 23 09:37:15 2013
@@ -20,92 +20,136 @@ package org.apache.sling.discovery;
/**
* A topology event is sent whenever a change in the topology occurs.
- *
- * This event object might be extended in the future with new event types
- * and methods.
+ *
+ * This event object might be extended in the future with new event types and
+ * methods.
+ *
* @see TopologyEventListener
*/
public class TopologyEvent {
- public static enum Type {
- TOPOLOGY_INIT, // Inform the service about the initial
topology state
- TOPOLOGY_CHANGING, // Inform the service about the fact that a
state change was detected
- // in the cluster topology and that a
voting amongst the members about
- // a new, valid view has just started.
- // Note that implementations might not
support this event at all.
- TOPOLOGY_CHANGED, // Inform the service about a state change
in the cluster topology.
- PROPERTIES_CHANGED // one or many properties have been changed
on an instance which is part
- // of the topology
- }
-
- private final Type type;
- private final TopologyView oldView;
- private final TopologyView newView;
-
- public TopologyEvent(final Type type, final TopologyView oldView, final
TopologyView newView) {
- if (type==null) {
- throw new IllegalArgumentException("type must not be
null");
- }
-
- if (type==Type.TOPOLOGY_INIT) {
- // then oldView is null
- if (oldView!=null) {
- throw new IllegalArgumentException("oldView
must be null");
- }
- // and newView must be not null
- if (newView==null) {
- throw new IllegalArgumentException("newView
must not be null");
- }
- } else if (type==Type.TOPOLOGY_CHANGING) {
- // then newView is null
- if (newView!=null) {
- throw new IllegalArgumentException("newView
must be null");
- }
- // and oldView must not be null
- if (oldView==null) {
- throw new IllegalArgumentException("oldView
must not be null");
- }
- } else {
- // in all other cases both oldView and newView must not
be null
- if (oldView==null) {
- throw new IllegalArgumentException("oldView
must not be null");
- }
- if (newView==null) {
- throw new IllegalArgumentException("newView
must not be null");
- }
- }
- this.type = type;
- this.oldView = oldView;
- this.newView = newView;
- }
-
- /**
- * Returns the type of this event
- * @return the type of this event
- */
- public Type getType() {
- return type;
- }
-
- /**
- * Returns the view which was valid up until now.
- * <p>
- * This is null in case of <code>TOPOLOGY_INIT</code>
- * @return the view which was valid up until now, or null in case of a
fresh instance start
- */
- public TopologyView getOldView() {
- return oldView;
- }
-
- /**
- * Returns the view which is currently (i.e. newly) valid.
- * <p>
- * This is null in case of <code>TOPOLOGY_CHANGING</code>
- * @return the view which is currently valid, or null in case of
<code>TOPOLOGY_CHANGING</code>
- */
- public TopologyView getNewView() {
- return newView;
- }
+ public static enum Type {
+ /**
+ * Inform the service about the initial topology state and is only sent
+ * once at bind-time.
+ * <p>
+ * This event type will be the first one a TopologyEventListener
+ * receives.
+ */
+ TOPOLOGY_INIT,
+
+ /**
+ * Inform the service about the fact that a state change was detected
in
+ * the topology/cluster and that a voting amongst the members about a
+ * new, valid topology/cluster view has just started.
+ * <p>
+ * An implementation must always send a TOPOLOGY_CHANGING before a
+ * TOPOLOGY_CHANGED.
+ */
+ TOPOLOGY_CHANGING,
+
+ /**
+ * Inform the service about a state change in the topology.
+ * <p>
+ * A state change includes:
+ * <ul>
+ * <li>A joining or leaving instance</li>
+ * <li>A restart of an instance - or more precisely: when the
+ * corresponding implementation bundle is deactivated/activated</li>
+ * <li>A cluster structure changed: either its members or the cluster
+ * view id. The cluster view id changes when an instance joins, leaves
+ * or was restarted (the bundle deactivated/activated)</li>
+ * </ul>
+ * <p>
+ * Note that tha TOPOLOGY_CHANGED can also include changes in the
+ * properties!
+ */
+ TOPOLOGY_CHANGED,
+
+ /**
+ * One or many properties have been changed on an instance which is
part
+ * of the topology.
+ * <p>
+ * This event is sent when otherwise the topology remains identical.
+ */
+ PROPERTIES_CHANGED
+
+ }
+
+ private final Type type;
+ private final TopologyView oldView;
+ private final TopologyView newView;
+
+ public TopologyEvent(final Type type, final TopologyView oldView,
+ final TopologyView newView) {
+ if (type == null) {
+ throw new IllegalArgumentException("type must not be null");
+ }
+
+ if (type == Type.TOPOLOGY_INIT) {
+ // then oldView is null
+ if (oldView != null) {
+ throw new IllegalArgumentException("oldView must be null");
+ }
+ // and newView must be not null
+ if (newView == null) {
+ throw new IllegalArgumentException("newView must not be null");
+ }
+ } else if (type == Type.TOPOLOGY_CHANGING) {
+ // then newView is null
+ if (newView != null) {
+ throw new IllegalArgumentException("newView must be null");
+ }
+ // and oldView must not be null
+ if (oldView == null) {
+ throw new IllegalArgumentException("oldView must not be null");
+ }
+ } else {
+ // in all other cases both oldView and newView must not be null
+ if (oldView == null) {
+ throw new IllegalArgumentException("oldView must not be null");
+ }
+ if (newView == null) {
+ throw new IllegalArgumentException("newView must not be null");
+ }
+ }
+ this.type = type;
+ this.oldView = oldView;
+ this.newView = newView;
+ }
+
+ /**
+ * Returns the type of this event
+ *
+ * @return the type of this event
+ */
+ public Type getType() {
+ return type;
+ }
+
+ /**
+ * Returns the view which was valid up until now.
+ * <p>
+ * This is null in case of <code>TOPOLOGY_INIT</code>
+ *
+ * @return the view which was valid up until now, or null in case of a
fresh
+ * instance start
+ */
+ public TopologyView getOldView() {
+ return oldView;
+ }
+
+ /**
+ * Returns the view which is currently (i.e. newly) valid.
+ * <p>
+ * This is null in case of <code>TOPOLOGY_CHANGING</code>
+ *
+ * @return the view which is currently valid, or null in case of
+ * <code>TOPOLOGY_CHANGING</code>
+ */
+ public TopologyView getNewView() {
+ return newView;
+ }
@Override
public String toString() {
