001 package org.hd.d.pg2k.svrCore.vars;
002
003 import java.io.IOException;
004 import java.util.BitSet;
005
006 /**
007 * Created by IntelliJ IDEA.
008 * User: Damon
009 * Date: 31-Aug-2004
010 * Time: 20:23:59
011 */
012
013 /**Basic variable manager interface.
014 * The variable manager may or may not be part of a pipeline.
015 */
016 public interface BasicVarMgrInterface
017 {
018 /**Set variable to the given value (the variable name and definition are implicit).
019 * The value set should be immediately readable with getVariable()
020 * as the "main" value of the variable even for global variables.
021 * <p>
022 * This is also used to send events,
023 * the last event value being the variable's value.
024 *
025 * @throws IOException in case of I/O difficulty
026 * @throws UnsupportedOperationException if a variable is set that
027 * we could never handle, eg a non-System-ID local variable at
028 * the client end of a tunnel
029 */
030 void setVariable(SimpleVariableValue newValue)
031 throws IOException,
032 UnsupportedOperationException;
033
034 /**Update a number of variables at once for efficiency; returns the number of variables set.
035 * Is passed a set of SimpleVariableValues and behaves as if it
036 * operates on all of them by calling setVariable() for each item
037 * in the set.
038 * <p>
039 * Furthermore it behaves as if the set operations are done in order,
040 * from low index to high index,
041 * unless variables are coalesced
042 * (multiple sets of the same simple variable can keep just the last value).
043 * Set operations of different variables may be re-ordered with respect to
044 * one another in order that redundancy may reduced for transmission
045 * and storage, so this implicitly allows, for example, events
046 * to be re-ordered with respect to non-event variables.
047 * <p>
048 * An implementation may "fail fast" on the first error/exception,
049 * or may attempt to continue and do as much as possible.
050 * <p>
051 * An implementation may throw an IllegalArgumentException on attempt to:
052 * set a variable with value of wrong type or incompatible definition,
053 * set a non-existent or read-only variable (or these may be ignored)
054 *
055 * @return the number of variable values set (the length of the array);
056 * never negative, never more than the number passed in
057 */
058 int setVariables(SimpleVariableValue[] newValues)
059 throws IOException;
060
061 /**Get a single variable value; returns null if no such value or wrong type.
062 * Implementations should, where possible,
063 * trim from the globalMap of returned values any apparently-stale data,
064 * so as to return only reasonably-live data to the caller.
065 * <p>
066 * Only the last event value for a given event variable
067 * is returned by this method.
068 *
069 * @param var definition of variable to fetch; never null
070 *
071 * @throws IOException in case of I/O difficulty
072 * @throws UnsupportedOperationException if a variable is requested that
073 * we could never supply, eg a non-System-ID local variable at
074 * the client end of a tunnel
075 */
076 SimpleVariableValue getVariable(SimpleVariableDefinition var)
077 throws IOException,
078 UnsupportedOperationException;
079
080 /**Get set of variable values altered on or after specified time, or get all values with -1; never null.
081 * This may be slow if there are many live variables.
082 * <p>
083 * Only the last event value of each event variable
084 * is returned by this method.
085 *
086 * @throws IOException in case of I/O difficulty
087 */
088 SimpleVariableValue[] getVariables(long changedSince)
089 throws IOException;
090
091
092 /**Get the current partial, or previous full, event set at the specified interval; never null.
093 * This is a simplified interface to return either the current event set
094 * that is being collected, or the previous completed set.
095 * <p>
096 * The current set is the most timely, but may not contain enough data
097 * to be meaningful if the new interval has just started.
098 * <p>
099 * The previous set is complete and thus most likely to have enough samples
100 * to be useful, but is not completely current.
101 * <p>
102 * If the requested event set is not available,
103 * an empty non-authoritative synthetic one is created and returned.
104 * Thus, with this interface, it is not possible to distinguish between
105 * there being no events in the given interval or simply no data at all,
106 * but this is relatively simple and safe to use.
107 *
108 * @param def event definition (must be for an event); never null
109 * @param intervalSelector never null
110 * @param current if true the current event set is returned,
111 * else the previous complete set is returned
112 *
113 * @return requested event set; never null
114 *
115 * @throws IllegalArgumentException if the request argument are invalid
116 */
117 EventVariableValue getEventValue(SimpleVariableDefinition def,
118 EventPeriod intervalSelector,
119 boolean current);
120
121 /**Get the specified event sets for the specified intervals; never null.
122 * This allows retrieval of zero or more event sets for the specified
123 * interval size.
124 * <p>
125 * Requests for more than SystemVariables.EVENT_SAMPLES_RETAINED in the
126 * past (or for the future!) cannot be satisfied and data will not be
127 * returned for them.
128 * <p>
129 * Usually not more than SystemVariables.EVENT_SAMPLES_RETAINED samples
130 * will be returned in response to any one request as a safety measure.
131 * <p>
132 * An implementation that is not an end-point may go upstream to fetch
133 * missing values and cache them to satisfy future requests.
134 * However, if unable to fetch authoritative data (quickly)
135 * then we will return null or non-authoritative data as appropriate for each slot;
136 * this does not throw IOException.
137 *
138 * @param def event definition (must be for an event); never null
139 * @param intervalSelector never null
140 * @param intervalNumber the number of the first interval
141 * for which data is potentially required;
142 * if too far in the past or future then possibly no data
143 * will be available,
144 * zero is used to select the "all" bucket
145 * @param whichValues each true bit represents a slot for which data is
146 * required, bit 0 indicating data from the slot within which
147 * firstIntervalTime is located, bit 1 the previous slot, etc;
148 * null is treated as the common case equivalent to just bit 0 set
149 *
150 * @return as many of the requested values as available,
151 * with as many of them authoritative as possible,
152 * with [0] corresponding to bit 0 in the BitSet;
153 * may contain nulls or be zero-length (or over-sized) but never null
154 */
155 EventVariableValue[] getEventValues(SimpleVariableDefinition def,
156 EventPeriod intervalSelector,
157 long intervalNumber,
158 BitSet whichValues);
159 }