Changeset 79 for trunk/EventBenchCore/src

Timestamp:

06/21/11 11:25:45 (14 years ago)

Author:

sherbold

Message:

• documentation

Location:

trunk/EventBenchCore/src/de/ugoe/cs/eventbench/data

Files:

• Event.java (modified) (11 diffs)
• IReplayable.java (modified) (1 diff)
• ReplayableEvent.java (modified) (1 diff)

trunk/EventBenchCore/src/de/ugoe/cs/eventbench/data/Event.java

@@ -3 +3 @@
 import java.security.InvalidParameterException;
 
-
-
+/**
+ * <p>
+ * Base class for all events. An event is described by its {@link #type} and its
+ * {@link #target}.
+ * </p>
+ * 
+ * @author Steffen Herbold
+ * @version 1.0
+ * 
+ * @param <T>
+ *            Can be used to declare that events belong to a specific platform
+ *            without subclassing.
+ */
 public class Event<T> {
-        
+
+        /**
+         * <p>
+         * Global start event that can be used to indicate the start of a sequence.
+         * </p>
+         */
         public static final Event<Object> STARTEVENT = new Event<Object>("START");
+
+        /**
+         * <p>
+         * Global end event that can be used to indicate the end of a sequence.
+         */
         public static final Event<Object> ENDEVENT = new Event<Object>("END");
-        
+
         /**
          * <p>
@@ -16 +37 @@
          */
         private String type;
-        
-        /**
-         * </p>
-         * Target of the event.
+
+        /**
+         * </p> Target of the event.
          */
         private String target = null;
-        
+
         /**
          * <p>
@@ -30 +50 @@
         private String targetShort = null;
 
-
+        /**
+         * Further information about the event that shall be included in its Id.
+         */
         private String idInfo = "";
-        
+
+        /**
+         * <p>
+         * Constructor. Creates a new Event with a given type.
+         * </p>
+         * 
+         * @param type
+         *            type of the event
+         */
         public Event(String type) {
-                if( type==null ) {
+                if (type == null) {
                         throw new InvalidParameterException("Event type must not be null");
                 }
@@ -40 +70 @@
         }
 
+        /**
+         * <p>
+         * Two events are equal, if their {@link #type} and {@link #target} are
+         * equal.
+         * </p>
+         * <p>
+         * See {@link Object#equals(Object)} for further information.
+         * </p>
+         * 
+         * @param other
+         *            Event that is compared to this
+         * @return true, if events are equal, false otherwise
+         */
         @Override
         public boolean equals(Object other) {
-                if( this==other ) {
+                if (this == other) {
                         return true;
                 }
                 if (other instanceof Event<?>) {
                         Event<?> otherEvent = (Event<?>) other;
-                        if( target!=null ) {
+                        if (target != null) {
                                 return type.equals(otherEvent.type)
-                                        && target.equals(otherEvent.target);
+                                                && target.equals(otherEvent.target);
                         } else {
                                 return type.equals(otherEvent.type)
-                                        && otherEvent.target==null;
+                                                && otherEvent.target == null;
                         }
                 } else {
@@ -58 +101 @@
                 }
         }
-        
+
+        /**
+         * <p>
+         * Returns {@link #getStandardId()} as String representation of the event.
+         * </p>
+         * 
+         * @return String represenation of the event
+         */
         @Override
         public String toString() {
@@ -64 +114 @@
         }
 
+        /**
+         * Informations about the event important for its Id that is neither target
+         * nor type.
+         * 
+         * @return {@link #idInfo} of the event
+         */
         public String getIdInfo() {
                 return idInfo;
         }
 
+        /**
+         * <p>
+         * If {@link #targetShort} is set, a shortend version of the Id is returned
+         * of the form {@link #targetShort}.{@link #type}.{@link #idInfo} is
+         * returned. Otherwise the standard Id is returned (see
+         * {@link #getStandardId()}).
+         * </p>
+         * 
+         * @return if available, shortend Id string; {@link #getStandardId()}
+         *         otherwise
+         */
         public String getShortId() {
                 String shortId = null;
-                if (targetShort!=null) {
-                        shortId = targetShort+"."+getType();
-                        if ( !"".equals(idInfo)) {
-                                shortId += "."+idInfo;
+                if (targetShort != null) {
+                        shortId = targetShort + "." + getType();
+                        if (!"".equals(idInfo)) {
+                                shortId += "." + idInfo;
                         }
                 } else {
@@ -81 +148 @@
         }
 
+        /**
+         * <p>
+         * Returns the Id string of the event. It has the form {@link #target}.
+         * {@link #type}.{@link #idInfo};
+         * <p>
+         * 
+         * @return Id string of the event
+         */
         public String getStandardId() {
                 String id = "";
-                if( target!=null ) {
+                if (target != null) {
                         id += target + ".";
                 }
                 id += getType();
-                if ( !"".equals(idInfo) ) {
+                if (!"".equals(idInfo)) {
                         id += "." + idInfo;
                 }
@@ -93 +168 @@
         }
 
+        /**
+         * <p>
+         * Returns the {@link #target} of the event.
+         * </p>
+         * 
+         * @return {@link #target} of the event
+         */
         public String getTarget() {
                 return target;
         }
-        
-        public String getTargetShort() {
+
+        /**
+         * <p>
+         * Returns the {@link #targetShort} of the event.
+         * </p>
+         * 
+         * @return {@link #targetShort} of the event
+         */
+        protected String getTargetShort() {
                 return targetShort;
         }
 
+        /**
+         * <p>
+         * Returns the {@link #type} of the event.
+         * </p>
+         * 
+         * @return {@link #type} of the event
+         */
         public String getType() {
                 return type;
         }
 
+        /*
+         * (non-Javadoc)
+         * 
+         * @see java.lang.Object#hashCode()
+         */
         @Override
         public int hashCode() {
@@ -110 +211 @@
                 int hash = 42;
                 hash = multiplier * hash + type.hashCode();
-                if( target!=null ) {
+                if (target != null) {
                         hash = multiplier * hash + target.hashCode();
                 }
@@ -117 +218 @@
         }
 
+        /**
+         * <p>
+         * Sets the {@link #idInfo} of the event. The idInfo is optional and
+         * contains information important for the event's Id that is neither target
+         * nor type.
+         * </p>
+         * 
+         * @param info
+         *            {@link #idInfo} of the event
+         */
         public void setIdInfo(String info) {
                 idInfo = info;
         }
-        
+
         /**
          * <p>
          * Sets the target of the event. Once set, the target cannot be changed.
-         * </p> 
-         * @param target target of the event
+         * </p>
+         * 
+         * @param target
+         *            target of the event
          * @return true, if target was changed, false otherwise
          */
         public boolean setTarget(String target) {
-                if( this.target!=null ) {
+                if (this.target != null) {
                         return false;
                 }
@@ -135 +248 @@
                 return true;
         }
-        
-        /**
-         * <p>
-         * Sets the short description of the event target. Once set, the target cannot be changed.
-         * </p> 
-         * @param targetShort short target description
+
+        /**
+         * <p>
+         * Sets the short description of the event target. Once set, the target
+         * cannot be changed.
+         * </p>
+         * 
+         * @param targetShort
+         *            short target description
          * @return true, if target was changed, false otherwise
          */
         public boolean setTargetShort(String targetShort) {
-                if( this.targetShort!=null ) {
+                if (this.targetShort != null) {
                         return false;
                 }

trunk/EventBenchCore/src/de/ugoe/cs/eventbench/data/IReplayable.java

@@ -1 +1 @@
 package de.ugoe.cs.eventbench.data;
 
+/**
+ * <p>
+ * This interface is used by {@link ReplayableEvent}to describe how events can
+ * be replayed. It can be used to define a sequence of fine-grained platform
+ * events that make up an abstract event.
+ * </p>
+ * 
+ * @author Steffen Herbold
+ * @version 1.0
+ */
 public interface IReplayable {
-        
+
+        /**
+         * <p>
+         * Returns a string to be written to the replay script that describes the
+         * replayable platform event.
+         * </p>
+         * 
+         * @return string for the replay script
+         */
         String getReplayXml();
-        
+
+        /**
+         * <p>
+         * Returns the target of the replayable.
+         * </p>
+         * 
+         * @return target of the replayable
+         */
         String getTarget();
 }

trunk/EventBenchCore/src/de/ugoe/cs/eventbench/data/ReplayableEvent.java

@@ -6 +6 @@
 import de.ugoe.cs.eventbench.IReplayDecorator;
 
+/**
+ * <p>
+ * Subclass of {@link Event} for events that contain all informations required
+ * for replaying them, i.e., generating scripts that can used for automated
+ * software execution.
+ * </p>
+ * 
+ * @author Steffen Herbold
+ * @version 1.0
+ * 
+ * @param <T>
+ *            Allows only types that extend {@link IReplayable} and is used to
+ *            define a list of replayables that describe the replay of the
+ *            event.
+ */
 public class ReplayableEvent<T extends IReplayable> extends Event<T> {
 
+        /**
+         * <p>
+         * List of {@link IReplayable}s of type T that describes the replay of an
+         * event. The {@link IReplayable}s can be interpreted as <it>sub-events</it>
+         * on the platform level that make up the abstract event.
+         * </p>
+         */
         private List<T> replayEvents = new LinkedList<T>();;
 
+        /**
+         * <p>
+         * Defines whether the replay is valid or invalid. It may be invalid, e.g.,
+         * due to errors during the generation of the event or lack of vital
+         * information.
+         * </p>
+         */
         private boolean replayValid = true;
-        
+
+        /**
+         * <p>
+         * {@link IReplayDecorator} used when replays of this type are written.
+         * </p>
+         */
         private IReplayDecorator decorator = null;
-        
+
+        /**
+         * <p>
+         * Constructor. Creates a new event with the given type.
+         * <p>
+         * 
+         * @param type
+         *            type of the event
+         * @see Event#Event(String)
+         */
         public ReplayableEvent(String type) {
                 super(type);
         }
-        
+
+        /**
+         * <p>
+         * Adds a new {@link IReplayable} of type T to the replay sequence.
+         * </p>
+         * 
+         * @param replayable
+         *            element that is added to the sequence
+         */
+        public void addReplayEvent(T replayable) {
+                replayEvents.add(replayable);
+        }
+
+        /**
+         * <p>
+         * Adds a {@link List}ist of {@link IReplayable} to the replay sequence.
+         * </p>
+         * 
+         * @param generatedReplaySeq
+         *            {@link List} that is added to the sequence
+         */
         public void addReplaySequence(List<T> generatedReplaySeq) {
                 replayEvents.addAll(generatedReplaySeq);
         }
 
-        public void addReplayEvent(T replayable) {
-                replayEvents.add(replayable);
+        /**
+         * <p>
+         * Returns the {@link IReplayDecorator} of the event.
+         * </p>
+         * 
+         * @return {@link IReplayDecorator} of the event; null if no decorator has
+         *         been set
+         */
+        public IReplayDecorator getReplayDecorator() {
+                return decorator;
         }
-        
+
         /**
          * <p>
          * Returns a the list of replay events.
-         * </p> 
+         * </p>
          * <p>
          * The return value is a copy of the list used internally!
          * </p>
-         * @return list of replay events. 
+         * 
+         * @return list of replay events.
          */
         public List<T> getReplayMessages() {
                 return new LinkedList<T>(replayEvents);
         }
-        
+
+        /**
+         * <p>
+         * Returns whether the replay is valid or not.
+         * </p>
+         * 
+         * @return true, if replay is valid; false otherwise.
+         */
         public boolean hasValidReplay() {
                 return replayValid;
         }
 
+        /**
+         * <p>
+         * Marks the replay as invalid. Once marked as invalid, it remains so and
+         * cannot be changed back to valid.
+         * </p>
+         */
         public void invalidateReplay() {
                 replayValid = false;
         }
 
+        /**
+         * <p>
+         * Sets the {@link IReplayDecorator} associated with the event.
+         * </p>
+         * 
+         * @param decorator
+         *            decorator associated with the event
+         */
         public void setDecorator(IReplayDecorator decorator) {
                 this.decorator = decorator;
         }
-        
-        public IReplayDecorator getReplayDecorator() {
-                return decorator;
-        }
 
 }