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

  1package javax.megaco.message.descriptor;
  2
  3import java.io.Serializable;
  4
  5
  6import javax.megaco.ParameterNotSetException;
  7import javax.megaco.association.LocalAddr;
  8import javax.megaco.association.MethodExtensionException;
  9import javax.megaco.association.SrvChngMethod;
 10import javax.megaco.association.SrvChngReason;
 11import javax.megaco.message.Descriptor;
 12import javax.megaco.message.DescriptorType;
 13
 14/**
 15 * The class extends JAIN MEGACO Descriptor. This class represents the service
 16 * change descriptor defined in the MEGACO protocol. This descriptor describes
 17 * the service change method, reason, delay, address, profile, mgcid, version,
 18 * the timestamp and any extension to it. Among these the service change method
 19 * is mandatory.
 20 */
 21public class SrvChngDescriptor extends Descriptor implements Serializable {
 22
 23	private SrvChngMethod srvChngMethod;
 24	private String svcChngMethodExtension;
 25	private SrvChngReason srvChngReason;
 26	private Integer srvChngDelay;
 27	private LocalAddr srvChngAddress;
 28	private String srvChngProfile;
 29	private LocalAddr handOffMGCId;
 30	private Integer protocolVersion;
 31	private String dateValue;
 32	private String timeValue;
 33	private String parameterExtension;
 34
 35	/**
 36	 * Constructs a SrvChng Descriptor. The service change descriptor class
 37	 * contain service change method and atleast one of service change method,
 38	 * reason, delay, address, profile, mgcid, version, the timestamp and any
 39	 * extension parameter.
 40	 */
 41	public SrvChngDescriptor() {
 42		super.descriptorId = DescriptorType.M_SERVICE_CHANGE_DESC;
 43	}
 44
 45	/**
 46	 * This method cannot be overridden by the derived class. This method
 47	 * returns that the descriptor identifier is of type descriptor SrvChng.
 48	 * This method overrides the corresponding method of the base class
 49	 * Descriptor.
 50	 * 
 51	 * @return Returns an integer value that identifies this service change
 52	 *         object as the type of service change descriptor. It returns the
 53	 *         the value M_SERVICE_CHANGE_DESC of a Service Change Descriptor.
 54	 */
 55	public int getDescriptorId() {
 56		return super.descriptorId;
 57	}
 58
 59	/**
 60	 * Gets the integer value which identifies the service change method.
 61	 * 
 62	 * @return Returns the integer value of service change method. The values of
 63	 *         the service change method are defined in SrvChngMethod. The
 64	 *         service change method is to be mandatorily set. If Service Change
 65	 *         method is not set then this method would return null.
 66	 */
 67	public SrvChngMethod getSrvChngMethod() {
 68		return this.srvChngMethod;
 69	}
 70
 71	/**
 72	 * This method sets the service change method. The values of the service
 73	 * change method are defined in SrvChngMethod. The service change method is
 74	 * to be mandatorily set.
 75	 * 
 76	 * @param method
 77	 *            The object reference of service change method.
 78	 * @throws IllegalArgumentException
 79	 *             : This exception is raised if the reference of Service Change
 80	 *             Method passed to this method is NULL.
 81	 */
 82	public void setSrvChngMethod(SrvChngMethod method) throws IllegalArgumentException {
 83		if (method == null) {
 84			throw new IllegalArgumentException("SrvChngMethod must not be null.");
 85		}
 86
 87		this.srvChngMethod = method;
 88	}
 89
 90	/**
 91	 * Gets the string value of the extended service change method.
 92	 * 
 93	 * @return Returns string value of the extended service change method. This
 94	 *         is to be set only if the service change method is set to
 95	 *         {@link javax.megaco.association.SrvChngMethod.M_EXTENSION}.
 96	 * @throws javax.megaco.association.MethodExtensionException
 97	 *             - Thrown if service change method has not been set to
 98	 *             {@link javax.megaco.association.SrvChngMethod.M_EXTENSION}.
 99	 */
100	public java.lang.String getSvcChngMethodExtension() throws javax.megaco.association.MethodExtensionException {
101
102		if (this.srvChngMethod == null || this.srvChngMethod.getSrvChngMethodId() != srvChngMethod.M_EXTENSION) {
103			throw new MethodExtensionException("SrvChngMethod must be set to: SVC_CHNG_METHOD_EXTENSION");
104		}
105		return this.svcChngMethodExtension;
106
107	}
108
109	/**
110	 * This method sets the extended service change method. This needs to be set
111	 * if and only if the service change method is {@link javax.megaco.association.SrvChngMethod.M_EXTENSION}.
112	 * 
113	 * @param extMethod
114	 *            - The string value of the extended service change method.
115	 * @throws javax.megaco.association.MethodExtensionException
116	 *             - Thrown if service change method has not been set to
117	 *             {@link javax.megaco.association.SrvChngMethod.M_EXTENSION}.
118	 * @throws IllegalArgumentException
119	 *             - Thrown if extension string does not follow the rules of the
120	 *             extension parameter, e.g, should start with X+ or X- etc.
121	 */
122	public void setSvcChngMethodExtension(java.lang.String extMethod) throws javax.megaco.association.MethodExtensionException, IllegalArgumentException {
123
124		if (this.srvChngMethod == null || this.srvChngMethod.getSrvChngMethodId() != srvChngMethod.M_EXTENSION) {
125			throw new MethodExtensionException("SrvChngMethod must be set to: SVC_CHNG_METHOD_EXTENSION");
126		}
127
128		DescriptorUtils.checkMethodExtensionRules(extMethod);
129
130		this.svcChngMethodExtension = extMethod;
131
132	}
133
134	/**
135	 * Gets the integer value which identifies the service change reason.
136	 * 
137	 * @return Returns the object reference corresponding to the service change
138	 *         reason. The values of the service change reason are defined in
139	 *         SrvChngReason. If the ServiceChangeReason is not set, then this
140	 *         method would return value null.
141	 */
142	public SrvChngReason getSrvChngReason() {
143		return this.srvChngReason;
144	}
145
146	/**
147	 * This method sets the service change reason. The values of the service
148	 * change reason are defined in SrvChngReason.
149	 * 
150	 * @param reasonCode
151	 *            The object reference to the corresponding service change
152	 *            reason.
153	 * @throws IllegalArgumentException
154	 *             - Thrown if the reference of ServiceChange reason passed to
155	 *             this method is NULL.
156	 */
157	public void setSrvChngReason(SrvChngReason reasonCode) throws IllegalArgumentException {
158
159		if (reasonCode == null) {
160			throw new IllegalArgumentException("SrvChngReason must not be null.");
161		}
162
163		this.srvChngReason = reasonCode;
164	}
165
166	/**
167	 * Gets the service change delay value received from peer in the service
168	 * change.
169	 * 
170	 * @return Returns the service change delay parameter as an integer value.
171	 * @throws javax.megaco.ParameterNotSetException
172	 *             - Thrown if service change delay parameter has not been set.
173	 */
174	public int getSrvChngDelay() throws javax.megaco.ParameterNotSetException {
175		if (!isSrvChngDelayPresent()) {
176			throw new ParameterNotSetException("SrvChngDelay is not present.");
177		}
178
179		return this.srvChngDelay.intValue();
180	}
181
182	/**
183	 * 
184	 This method sets the service change delay value.
185	 * 
186	 * @param delay
187	 *            The service change delay as an integer value.
188	 * @throws IllegalArgumentException
189	 *             : This exception is raised if the value of service change
190	 *             delay passed to this method is less than 0.
191	 */
192	public void setSrvChngDelay(int delay) throws IllegalArgumentException {
193		if (delay <= 0) {
194			throw new IllegalArgumentException("Delay must be greater than zero.");
195		}
196
197		this.srvChngDelay = new Integer(delay);
198	}
199
200	/**
201	 * Identifies whether the service change delay is present.
202	 * 
203	 * @return Returns true if the service change delay is present.
204	 */
205	public boolean isSrvChngDelayPresent() {
206		return this.srvChngDelay != null;
207	}
208
209	/**
210	 * Gets the service change address. If the service change command has been
211	 * received from peer, then it refers to the the new transport address the
212	 * peer intends to use subsequently.
213	 * 
214	 * @return Returns the service change address. If the service change address
215	 *         is missing, then the method would return NULL.
216	 */
217	public LocalAddr getSrvChngAddress() {
218		return this.srvChngAddress;
219	}
220
221	/**
222	 * This method sets the service change address. This is not a mandatory
223	 * parameter.
224	 * 
225	 * @param LocalAddr
226	 *            The object reference of service change address.
227	 * @throws IllegalArgumentException
228	 *             - Thrown if a parameter in service change address is set such
229	 *             that it is invalid.
230	 */
231	public void setSrvChngAddress(LocalAddr localAddr) throws IllegalArgumentException {
232
233		// FIXME: not present in jdoc
234		if (localAddr == null) {
235			throw new IllegalArgumentException("LocalAddr must not be null.");
236		}
237		// FIXME: add error checks?
238
239		this.srvChngAddress = localAddr;
240
241	}
242
243	/**
244	 * Gets the service change profile value received from peer in the service
245	 * change.
246	 * 
247	 * @return Returns the service change profile parameter as a string value.
248	 *         If the service change profile is not set then it returns a NULL
249	 *         value.
250	 */
251	public java.lang.String getSrvChngProfile() {
252		return this.srvChngProfile;
253	}
254
255	/**
256	 * This method sets the service change profile value.
257	 * 
258	 * @param profile
259	 *            The service change profile as a string value.
260	 * @throws IllegalArgumentException
261	 *             - Thrown if service change profile parameter has invalid
262	 *             format.
263	 */
264	public void setSrvChngProfile(java.lang.String profile) throws IllegalArgumentException {
265		if (profile == null) {
266			throw new IllegalArgumentException("profile must not be null.");
267		}
268
269		DescriptorUtils.checkSrvcChngProfileRules(profile);
270
271		this.srvChngProfile = profile;
272	}
273
274	/**
275	 * Gets the identity of the MGC to which the association is to be handoffed.
276	 * As specified in the protocol, in case of failure of MGC, it would handoff
277	 * the control of the MG to the new MGC. This is conveyed using service
278	 * change command on ROOT termination, with service change method set to
279	 * M_HANDOFF and transport parameters of the new MGC
280	 * specified in the mgcidToTry field of the service change descriptor. This
281	 * mgcidToTry field of the service change descriptor is represented using
282	 * HandedOffMGCId field on this class.
283	 * 
284	 * @return Returns the identity of the MGC to which the association is to be
285	 *         handoffed.
286	 */
287	public LocalAddr getHandOffMGCId() {
288		return this.handOffMGCId;
289	}
290
291	/**
292	 * This method sets the identity of the MGC to which the association is to
293	 * be handoffed.
294	 * 
295	 * As specified in the protocol, in case of failure of MGC, it would handoff
296	 * the control of the MG to the new MGC. This is conveyed using service
297	 * change command on ROOT termination, with service change method set to
298	 * M_HANDOFF and transport parameters of the new MGC
299	 * specified in the mgcidToTry field of the service change descriptor. This
300	 * mgcidToTry field of the service change descriptor is represented using
301	 * HandedOffMGCId field on this class.
302	 * 
303	 * @param mgcidToTry
304	 *            The identity of the MGC to which the association is to be
305	 *            handoffed.
306	 * @throws IllegalArgumentException
307	 *             - Thrown if a parameter in mgc Id is set such that it is
308	 *             invalid.
309	 */
310	public void setHandOffMGCId(LocalAddr mgcidToTry) throws IllegalArgumentException {
311
312		// FIXME: not present in jdoc
313		if (mgcidToTry == null) {
314			throw new IllegalArgumentException("LocalAddr must not be null.");
315		}
316
317		if (srvChngMethod == null || srvChngMethod.getSrvChngMethodId() != srvChngMethod.M_HANDOFF) {
318			throw new IllegalArgumentException("SrvChngMethodId must be set to: SVC_CHNG_METHOD_HANDOFF.");
319		}
320
321		// FIXME: add error checks?
322		this.handOffMGCId = mgcidToTry;
323
324	}
325
326	/**
327	 * Gets the protocol version value received from peer in the service change.
328	 * This is ther protocol version after negotiation.
329	 * 
330	 * @return Returns the protocol version parameter as an integer value.
331	 * @throws javax.megaco.ParameterNotSetException
332	 *             - Thrown if protocol version has not been set.
333	 */
334	public int getProtocolVersion() throws javax.megaco.ParameterNotSetException {
335		if (!isProtocolVersionPresent()) {
336			throw new ParameterNotSetException("Protocol Version has not been set.");
337		}
338
339		return this.protocolVersion.intValue();
340	}
341
342	/**
343	 * This method sets the protocol version value.
344	 * 
345	 * @param version
346	 *            The protocol version as an integer value.
347	 * @throws IllegalArgumentException
348	 *             - Thrown if service change version parameter is less than or
349	 *             equal to 0.
350	 */
351	public void setProtocolVersion(int version) throws IllegalArgumentException {
352
353		if (version <= 0) {
354			throw new IllegalArgumentException("Protocol Version must be greater than zero.");
355		}
356
357		this.protocolVersion = new Integer(version);
358
359	}
360
361	/**
362	 * Identifies whether the protocol version is present.
363	 * 
364	 * @return Returns true if the protocol version is present.
365	 */
366	public boolean isProtocolVersionPresent() {
367		return this.protocolVersion != null;
368	}
369
370	/**
371	 * Gets the string value of the date value of timestamp in service change
372	 * descriptor.
373	 * 
374	 * @return Returns string value of the date value of timestamp in service
375	 *         change. If the date value of timestamp in service change is not
376	 *         set then a NULL value is returned.
377	 */
378	public java.lang.String getDateValue() {
379		return this.dateValue;
380	}
381
382	/**
383	 * This method sets the date value of timestamp in service change
384	 * descriptor.
385	 * 
386	 * @param dateValue
387	 *            The string value of the date value of timestamp in service
388	 *            change descriptor.
389	 * @throws IllegalArgumentException
390	 *             - Thrown if date value of timestamp in service change
391	 *             descriptor is not of 8 digit length.
392	 */
393	public void setDateValue(java.lang.String dateValue) throws IllegalArgumentException {
394
395		if (dateValue == null) {
396			new IllegalArgumentException("DateValue must nto be null.");
397		}
398
399		DescriptorUtils.checkTimeStampRules(dateValue);
400		this.dateValue = dateValue;
401	}
402
403	/**
404	 * Gets the string value of the time value of timestamp in service change
405	 * descriptor.
406	 * 
407	 * @return Returns string value of the time value of timestamp in service
408	 *         change descriptor. If the time value of timestamp in service
409	 *         change descriptor is not set then a NULL value is returned.
410	 */
411	public java.lang.String getTimeValue() {
412		return this.timeValue;
413	}
414
415	/**
416	 * This method sets the time value of timestamp in service change
417	 * descriptor.
418	 * 
419	 * @param timeValue
420	 *            The string value of the time value of timestamp in service
421	 *            change descriptor.
422	 * @throws IllegalArgumentException
423	 *             - Thrown if time value of timestamp in service change
424	 *             descriptor is not of 8 digit length.
425	 */
426	public void setTimeValue(java.lang.String timeValue) throws IllegalArgumentException {
427
428		if (timeValue == null) {
429			new IllegalArgumentException("TimeValue must nto be null.");
430		}
431
432		DescriptorUtils.checkTimeStampRules(timeValue);
433		this.timeValue = timeValue;
434	}
435
436	/**
437	 * Gets the string value of the extended service change parameter.
438	 * 
439	 * @return Returns string value of the extended service change parameter. If
440	 *         the service change parameter is not set then this a NULL value is
441	 *         returned.
442	 */
443	public java.lang.String getParameterExtension() {
444		return this.parameterExtension;
445	}
446
447	/**
448	 * This method sets the extended service change parameter.
449	 * 
450	 * @param extMethod
451	 *            The string value of the extended service change parameter.
452	 * @throws IllegalArgumentException
453	 *             - Thrown if extension string does not follow the rules of the
454	 *             extension parameter, e.g, should start with X+ or X- etc.
455	 */
456	public void setParameterExtention(java.lang.String extMethod) throws IllegalArgumentException {
457		if (extMethod == null) {
458			new IllegalArgumentException("ExtMethod must nto be null.");
459		}
460
461		DescriptorUtils.checkMethodExtensionRules(extMethod);
462
463		this.parameterExtension = extMethod;
464	}
465
466}