/protocols/jain-megaco/megaco-api/src/main/java/javax/megaco/message/descriptor/ObservedEvent.java

  1package javax.megaco.message.descriptor;
  2
  3import java.io.Serializable;
  4
  5
  6import javax.megaco.MethodInvocationException;
  7import javax.megaco.pkg.PkgEventItem;
  8import javax.megaco.pkg.PkgItemStr;
  9
 10/**
 11 * The ObservedEvent object is a class that shall be used to set the observed
 12 * events and the stream id in which it was observed along with optionally the
 13 * time at which it was detected. The class optionally provides interface to
 14 * specify the package name, item name and the associated parameters in the
 15 * string format. This is an independent class derived from java.util.Object and
 16 * shall not have any derived classes.
 17 */
 18public class ObservedEvent implements Serializable {
 19
 20	private PkgEventItem eventItem;
 21	private PkgItemStr eventItemStr;
 22	private TimeStamp timeStamp;
 23	private Integer streamId;
 24
 25	/**
 26	 * Constructs Observed Event parameter Object. This is to be set within an
 27	 * observed event descriptor.
 28	 * 
 29	 * @param eventItem
 30	 * @throws IllegalArgumentException
 31	 *             - Thrown if an invalid event id is set.
 32	 */
 33	public ObservedEvent(PkgEventItem eventItem) throws IllegalArgumentException {
 34
 35		// FIXME: add error check on invalid event?
 36		if (eventItem == null) {
 37			throw new IllegalArgumentException("PkgEventItem must not be null");
 38
 39		}
 40
 41		this.eventItem = eventItem;
 42	}
 43
 44	/**
 45	 * 
 46	 * Constructs Observed Event parameter object with the PkgItemStr object.
 47	 * This method would be used if the package parameters are to be conveyed in
 48	 * the string format. This is to be set within an event buffer descriptor.
 49	 * 
 50	 * @param eventItemStr
 51	 * @throws IllegalArgumentException
 52	 *             - Thrown if an invalid eventItemStr object reference is set.
 53	 */
 54	public ObservedEvent(PkgItemStr eventItemStr) throws IllegalArgumentException {
 55		if (eventItemStr == null) {
 56			throw new IllegalArgumentException("PkgItemStr must not be null");
 57
 58		}
 59
 60		this.eventItemStr = eventItemStr;
 61	}
 62
 63	/**
 64	 * The method can be used to get the pkdgName as set in the observed event
 65	 * descriptor. This method gives the package information, the attached event
 66	 * information and the parameter name and value for the event id.
 67	 * 
 68	 * @return The object reference for the megaco package, which has the object
 69	 *         reference for megaco package event and which in turn has the
 70	 *         reference for the parameter info. If the parameter has not been
 71	 *         set, then this method shall return NULL.
 72	 */
 73	public PkgEventItem getMegacoPkgEvtItem() {
 74		return this.eventItem;
 75
 76	}
 77
 78	/**
 79	 * The method can be used to get the pkdgName as set in the observed event
 80	 * descriptor. This method gives the package information, the attached event
 81	 * information and the parameter name and value. As compares to the
 82	 * getMegacoPkgEvtItem() method, this method returns the package parameters
 83	 * in the string format.
 84	 * 
 85	 * @return The object reference for the megaco package item. This class
 86	 *         holds information about package name, item name and the
 87	 *         parameters in the string format. If the parameter has not been
 88	 *         set, then this method shall return NULL.
 89	 */
 90	public PkgItemStr getMegacoPkgItemStr() {
 91		return this.eventItemStr;
 92	}
 93
 94	/**
 95	 * The method can be used to get stream id in the event descriptor.
 96	 * 
 97	 * @return streamId - The integer value of the stream id shall be returned.
 98	 *         This shall be returned only if the streamId is present in the
 99	 *         event parameter of the event descriptor.
100	 * @throws IllegalStateException
101	 *             - Thrown if streamId has not been set. Thus this method
102	 *             should be called only after verifying that the streamId is
103	 *             set using isStreamIdPresent
104	 */
105	public int getStreamId() throws IllegalStateException {
106		if (!isStreamIdPresent()) {
107			throw new IllegalStateException("StreamId must be present");
108		}
109		return this.streamId.intValue();
110	}
111
112	/**
113	 * The method can be used to set stream id in the event descriptor. This
114	 * automatically sets the value of stream id present in the event parameter
115	 * object to true.
116	 * 
117	 * @param streamId
118	 *            - The integer value of the stream id shall be set.
119	 * @throws IllegalArgumentException
120	 *             - Thrown if streamId is set with an invalid value.
121	 */
122	public void setStreamId(int streamId) throws IllegalArgumentException {
123		if (streamId <= 0) {
124			throw new IllegalArgumentException("StreamId must be greater than zero.");
125		}
126		this.streamId = new Integer(streamId);
127	}
128
129	/**
130	 * The method can be used to find if the stream id is present in the current
131	 * object.
132	 * 
133	 * @return Returns true if the stream id is present. This needs to be
134	 *         checked before getting the stream id from this object.
135	 */
136	public boolean isStreamIdPresent() {
137		return this.streamId != null;
138	}
139
140	/**
141	 * The method is used to retrieve the time stamp at which the event was
142	 * detected.
143	 * 
144	 * @return timeStamp - The object reference for the timestamp. It returns a
145	 *         NULL value when not set.
146	 */
147	public TimeStamp getTimeStamp() {
148		return this.timeStamp;
149	}
150
151	/**
152	 * The method is used to set the time stamp at which the event was detected.
153	 * 
154	 * @param timeStamp
155	 *            - The object reference for the timestamp.
156	 * @throws IllegalArgumentException
157	 *             - Thrown if timestamp is set with an invalid value.
158	 */
159	public void setTimeStamp(TimeStamp timeStamp) throws IllegalArgumentException {
160
161		// FIXME: add checks for invalid value?
162		if (timeStamp == null) {
163			throw new IllegalArgumentException("TimeStamp must not be null");
164		}
165
166		this.timeStamp = timeStamp;
167	}
168
169	public java.lang.String toString() {
170		return super.toString();
171	}
172
173}