01: /*
02: * $RCSfile: Negotiable.java,v $
03: *
04: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
05: *
06: * Use is subject to license terms.
07: *
08: * $Revision: 1.1 $
09: * $Date: 2005/02/11 04:57:50 $
10: * $State: Exp $
11: */package javax.media.jai.remote;
12:
13: import java.io.Serializable;
14:
15: /**
16: * An interface that defines objects that can be negotiated upon.
17: * Negotiation amongst objects is performed using the
18: * <code>negotiate()</code> method. This method can be used to
19: * perform a chaining of successful negotiations, i.e., the results
20: * of one successful negotiation can be used to negotiate with another
21: * <code>Negotiable</code> and so on. In order to retrieve a single
22: * negotiated value out of the <code>Negotiable</code>, the
23: * <code>getNegotiatedValue()</code> method can be used at any point
24: * during this series of negotiations.
25: *
26: * @since JAI 1.1
27: */
28: public interface Negotiable extends Serializable {
29:
30: /**
31: * Returns a <code>Negotiable</code> object that represents the
32: * set intersection of this <code>Negotiable</code> with the
33: * given <code>Negotiable</code>. The returned <code>Negotiable</code>
34: * represents the support that is common to both the
35: * <code>Negotiable</code>s. If the negotiation fails, i.e there is
36: * no common subset, null is returned.
37: *
38: * <p> If the supplied argument is null, negotiation will fail and
39: * null will be returned, as it is not possible to negotiate with a
40: * null value. It may, however, be noted that it is valid for
41: * <code>getNegotiatedValue()</code> to return null, i.e the single
42: * value result of the negotiation can be null.
43: *
44: * @param other The <code>Negotiable</code> object to negotiate with.
45: * @returns The <code>Negotiable</code> that represents the subset
46: * common to this and the given <code>Negotiable</code>.
47: * <code>null</code> is returned if there is no common subset.
48: */
49: Negotiable negotiate(Negotiable other);
50:
51: /**
52: * Returns a value that is valid for this <code>Negotiable</code>.
53: * If more than one value is valid for this <code>Negotiable</code>,
54: * this method can choose one arbitrarily, e.g. picking the first one
55: * or by having static preferences amongst the valid values. Which of the
56: * many valid values is returned is upto the particular implementation
57: * of this method.
58: *
59: * @returns The negotiated value.
60: */
61: Object getNegotiatedValue();
62:
63: /**
64: * Returns the <code>Class</code> of the object that would be returned
65: * from the <code>getNegotiatedValue</code> method on a successful
66: * negotiation. This method can be used to learn what the
67: * <code>Class</code> of the negotiated value will be if the negotiation
68: * is successful. Implementing classes are encouraged to return an
69: * accurate <code>Class</code> from this method if at all possible.
70: * However it is permissible to return null, if the <code>Class</code>
71: * of the negotiated value is indeterminate for any reason.
72: *
73: * @returns the <code>Class</code> of the negotiated value.
74: */
75: Class getNegotiatedValueClass();
76: }
|