20 * |
20 * |
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 * or visit www.oracle.com if you need additional information or have any |
22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. |
23 * questions. |
24 */ |
24 */ |
|
25 package jdk.incubator.sql2; |
25 |
26 |
26 package jdk.incubator.sql2; |
27 import java.io.Serializable; |
27 |
28 |
28 /** |
29 /** |
29 * An attribute of a {@link Session} that can be configured to influence its |
30 * An attribute of a {@link Session} that can be configured to influence its |
30 * behavior. Implementors of this interface define the properties of |
31 * behavior. implementers of this interface define the properties of |
31 * {@link Session}s. The {@link Session.Builder#property} method is used to set the values |
32 * {@link Session}s. The {@link Session.Builder#property} method is used to set |
32 * of {@link Session} properties. |
33 * the values of {@link Session} properties. |
33 * |
34 * |
34 * Implementations must be thread safe. |
35 * Implementations must be thread safe. |
35 * |
36 * |
36 */ |
37 */ |
37 public interface SessionProperty { |
38 public interface SessionProperty extends Serializable { |
38 |
39 |
39 /** |
40 /** |
40 * Return the name of this {@link SessionProperty}. |
41 * Return the name of this {@code SessionProperty}. |
41 * |
42 * |
42 * @return the name of this {@link SessionProperty} |
43 * @return the name of this {@code SessionProperty} |
43 */ |
44 */ |
44 public String name(); |
45 public String name(); |
45 |
46 |
46 /** |
47 /** |
47 * Return the type of the value of this {@link SessionProperty}. Any value |
48 * Return the type of the value of this {@code SessionProperty}. Any value set |
48 * set for this property must be assignable to this type. |
49 * for this property must be assignable to this type. |
49 * |
50 * |
50 * @return the type of the values of this {@link SessionProperty} |
51 * @return the type of the values of this {@code SessionProperty} |
51 */ |
52 */ |
52 public Class<?> range(); |
53 public Class<?> range(); |
53 |
54 |
54 /** |
55 /** |
55 * Determine whether a value is valid for this {@link SessionProperty}. Returns |
56 * Determine whether a value is valid for this {@code SessionProperty}. |
56 * {@code true} if {@code value} is valid and {@code false} otherwise. |
57 * Returns {@code true} if {@code value} is valid and {@code false} otherwise. |
57 * |
58 * |
58 * @param value a value for this {@link SessionProperty} |
59 * @param value a value for this {@code SessionProperty} |
59 * @return {@code true} iff {@code value} is valid for this {@link SessionProperty} |
60 * @return {@code true} iff {@code value} is valid for this |
|
61 * {@code SessionProperty} |
60 */ |
62 */ |
61 public default boolean validate(Object value) { |
63 public default boolean validate(Object value) { |
62 return (value == null && this.range() == Void.class) || this.range().isInstance(value); |
64 return (value == null && this.range() == Void.class) || this.range().isInstance(value); |
63 } |
65 } |
64 |
66 |
65 /** |
67 /** |
66 * Return the value for this property to use if no other value is set. For |
68 * Return the value for this property to use if no other value is set. For |
67 * this to have any meaning for a user defined property the property must be |
69 * this to have any meaning for a user defined property the property must be |
68 * registered with the {@link DataSource} by calling |
70 * registered with the {@link DataSource} by calling |
69 * {@link DataSource.Builder#registerSessionProperty}. |
71 * {@link DataSource.Builder#registerSessionProperty}. |
70 * |
72 * |
71 * @return the default value or {@code null} if there is no default value |
73 * @return the default value or {@code null} if there is no default value |
72 */ |
74 */ |
73 public Object defaultValue(); |
75 public Object defaultValue(); |
74 |
76 |
75 /** |
77 /** |
76 * Returns true if this {@link SessionProperty} contains sensitive information |
78 * Returns true if this {@code SessionProperty} contains sensitive information |
77 * such as a password or encryption key. |
79 * such as a password or encryption key. |
78 * |
80 * |
79 * @return true iff this is sensitive |
81 * @return true iff this is sensitive |
80 */ |
82 */ |
81 public boolean isSensitive(); |
83 public boolean isSensitive(); |
83 /** |
85 /** |
84 * Creates and submits zero or more {@link Operation}s that will configure the |
86 * Creates and submits zero or more {@link Operation}s that will configure the |
85 * {@link Session} to have the specified property value. Returns {@code true} |
87 * {@link Session} to have the specified property value. Returns {@code true} |
86 * if any {@link Operation}s were submitted. {@code false} otherwise. |
88 * if any {@link Operation}s were submitted. {@code false} otherwise. |
87 * |
89 * |
88 * Called by {@link Session.Builder#build()} to configure a {@link Session} as |
90 * Potentially called when an attach {@link Operation} is executed to |
89 * specified in the {@link Session.Builder#property} method. SessionProperties |
91 * configure a {@link Session} as specified in the |
90 * known to the implementation may return {@code false} and rely on the |
92 * {@link Session.Builder#property} method. SessionProperties known to the |
91 * implementation to do the right thing. |
93 * implementation may return {@code false} and rely on the implementation to |
|
94 * do the right thing. |
92 * |
95 * |
93 * @param group an {@link OperationGroup} which will be the container of the |
96 * @param group an {@link OperationGroup} which will be the container of the |
94 * submitted {@link Operation}s, if any |
97 * submitted {@link Operation}s, if any |
95 * @param value the value to which the property is to be set. May be null if |
98 * @param value the value to which the property is to be set. May be |
96 * {@link range()} is {@link Void}. |
99 * {@code null} if {@link range()} is {@link Void}. |
97 * @return true if any {@link Operation}s were submitted, false otherwise |
100 * @return true if any {@link Operation}s were submitted, false otherwise |
98 * @throws IllegalStateException if it is not possible to configure the |
101 * @throws IllegalStateException if it is not possible to configure the |
99 * {@link Session} as specified. |
102 * {@link Session} as specified. |
100 * @throws IllegalArgumentException if {@code this.validate(value)} returns |
103 * @throws IllegalArgumentException if {@code this.validate(value)} returns |
101 * {@code false} |
104 * {@code false} |