001: /*
002: * $Id: CallRequest.java,v 1.20 2007/03/15 17:08:27 agoubard Exp $
003: *
004: * Copyright 2003-2007 Orange Nederland Breedband B.V.
005: * See the COPYRIGHT file for redistribution and use restrictions.
006: */
007: package org.xins.common.service;
008:
009: import java.io.Serializable;
010:
011: /**
012: * Abstraction of a request for a <code>ServiceCaller</code> call. Specific
013: * service callers typically only accept a single type of request, derived
014: * from this class.
015: *
016: * <p>This class is not thread-safe.
017: *
018: * <h2>Implementations</h2>
019: *
020: * <p>Implementations of this class should stick to the following rules:
021: *
022: * <ul>
023: * <li>the {@link #describe()} method must be implemented;
024: * <li>only a single non-argument constructor should be provided, all
025: * settings should be done using setter methods;
026: * <li>a service caller-specific getter should be added for the associated
027: * call config object, this method should return the caller-specific
028: * call config object (a subclass of class {@link CallConfig}).
029: * </ul>
030: *
031: * @version $Revision: 1.20 $ $Date: 2007/03/15 17:08:27 $
032: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
033: *
034: * @since XINS 1.0.0
035: *
036: * @see ServiceCaller
037: */
038: public abstract class CallRequest implements Serializable {
039:
040: /**
041: * The <code>CallConfig</code> associated with this request, if any. Can be
042: * -and initially is- <code>null</code>.
043: */
044: private CallConfig _callConfig;
045:
046: /**
047: * Describes this request. The description should be trimmed and should fit
048: * in a sentence. Good examples include <code>"LDAP request #1592"</code>
049: * and <code>"request #12903"</code>.
050: *
051: * @return
052: * the description of this request, should never be <code>null</code>,
053: * should never be empty and should never start or end with whitespace
054: * characters.
055: */
056: public abstract String describe();
057:
058: /**
059: * Constructs a new <code>CallRequest</code>. This constructor is only
060: * available to subclasses, since this class is <code>abstract</code>.
061: */
062: protected CallRequest() {
063:
064: // empty
065: }
066:
067: /**
068: * Returns a textual presentation of this object.
069: *
070: * <p>The implementation of this method in class {@link CallRequest}
071: * returns {@link #describe()}.
072: *
073: * @return
074: * a textual presentation of this object, should never be
075: * <code>null</code>.
076: */
077: public String toString() {
078: return describe();
079: }
080:
081: /**
082: * Retrieves the associated call configuration, if any.
083: *
084: * @return
085: * the associated call configuration, or <code>null</code> if none is.
086: *
087: * @since XINS 1.1.0
088: */
089: protected final CallConfig getCallConfig() {
090: return _callConfig;
091: }
092:
093: /**
094: * Sets the call configuration associated with this request.
095: *
096: * @param config
097: * the call configuration to associate with this request, or
098: * <code>null</code> if none should be.
099: *
100: * @since XINS 1.1.0
101: */
102: protected final void setCallConfig(CallConfig config) {
103: _callConfig = config;
104: }
105: }
|