001: /*_############################################################################
002: _##
003: _## SNMP4J-Agent - MOTable.java
004: _##
005: _## Copyright (C) 2005-2007 Frank Fock (SNMP4J.org)
006: _##
007: _## Licensed under the Apache License, Version 2.0 (the "License");
008: _## you may not use this file except in compliance with the License.
009: _## You may obtain a copy of the License at
010: _##
011: _## http://www.apache.org/licenses/LICENSE-2.0
012: _##
013: _## Unless required by applicable law or agreed to in writing, software
014: _## distributed under the License is distributed on an "AS IS" BASIS,
015: _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: _## See the License for the specific language governing permissions and
017: _## limitations under the License.
018: _##
019: _##########################################################################*/
020:
021: package org.snmp4j.agent.mo;
022:
023: import org.snmp4j.smi.OID;
024: import org.snmp4j.agent.MOScope;
025: import org.snmp4j.smi.Variable;
026: import org.snmp4j.agent.ManagedObject;
027:
028: /**
029: * The <code>MOTable</code> interface describes SNMP conceptual tables.
030: * In general, a conceptual table can be implemented in two different ways:
031: * <ul>
032: * <li>For large tables, a virtual table model is best suited where rows are
033: * created on behalf of a request only. The instrumentation directly propagates
034: * data to the managed objects without holding the data in a table model.</li>
035: * <li>For small or medium size tables, holding the data in (non virtual) table
036: * model provides data caching and decoupling of the instrumentation.</li>
037: * </ul>
038: * @author Frank Fock
039: * @version 1.0
040: */
041: public interface MOTable extends ManagedObject {
042:
043: /**
044: * Finds the object identifier of the first object instance in the specified
045: * range.
046: * @param range
047: * a <code>MOScope</code> specifying the search range.
048: * @return
049: * the OID of the lexicographic first instance in the search range or
050: * <code>null</code> if no such instance exists.
051: */
052: OID find(MOScope range);
053:
054: /**
055: * Returns the zero based column index for the specified column
056: * sub-identifier.
057: * @param id
058: * a column sub-identifier (normally one based) as defined in the MIB
059: * specification.
060: * @return
061: * a value greater or equal to zero denoting the column index
062: * of the column associated with <code>id</code>. The column index
063: * points into the column array returned by {@link #getColumns}.
064: * A value less than zero indicates that such a column does not exists
065: * currently but could be inserted at the <code>(-n)-1</code> position
066: * if <code>n</code> is the returned value.
067: */
068: int getColumnIndex(int id);
069:
070: /**
071: * Gets the column definitions for this table.
072: * @return
073: * an array with the column definitions of this table.
074: */
075: MOColumn[] getColumns();
076:
077: /**
078: * Gets the column definition for the specified column.
079: * @param index
080: * the (zero-based) column index.
081: * @return
082: * a <code>MOColumn</code> instance describing the attributes of requested
083: * column.
084: */
085: MOColumn getColumn(int index);
086:
087: /**
088: * Returns a <code>MOTableCellInfo</code> instance for the supplied
089: * cell OID. The returned object contains the index, column index, and
090: * column ID of the specified cell, if available.
091: * @param oid
092: * cell instance OID.
093: * @return
094: * a <code>MOTableCellInfo</code> instance with the index, column index
095: * and column ID of the specified cell if available.
096: */
097: MOTableCellInfo getCellInfo(OID oid);
098:
099: /**
100: * Returns the number of columns in this table.
101: * @return
102: * the column count.
103: */
104: int getColumnCount();
105:
106: /**
107: * Gets the index definition of this table.
108: *
109: * @return
110: * a MOTableIndex instance containing the sub-index definitions for this
111: * table.
112: */
113: MOTableIndex getIndexDef();
114:
115: /**
116: * Returns the index part of a column instance identifier of this table.
117: * @param instanceIdentifier
118: * the OID of a column instance. The returned result is undefined, when
119: * this OID is not a column instance OID.
120: * @return
121: * an OID representing the index OID of the row identified by the
122: * <code>instanceIdentifier</code> column instance OID.
123: */
124: OID getIndexPart(OID instanceIdentifier);
125:
126: /**
127: * Gets the table model of this table.
128: * @return
129: * a MOTableModel instance.
130: */
131: MOTableModel getModel();
132:
133: /**
134: * Returns the OID of the table entry.
135: * @return
136: * a table entry OID (including the .1 suffix).
137: */
138: OID getOID();
139:
140: /**
141: * Returns an array of variables where each variable corresponds to the
142: * column with the same index. If a column has a default value, the returned
143: * variable is not <code>null</code> and contains that default value.
144: *
145: * @return
146: * the default variables for a newly created row as an array of
147: * <code>Variable</code> instances.
148: */
149: Variable[] getDefaultValues();
150:
151: /**
152: * Gets the value of the cell instance with the specified instance OID.
153: * @param cellOID
154: * the instance OID of the requested cell.
155: * @return
156: * the value of the cell or <code>null</code> if such a cell does not
157: * exist.
158: */
159: Variable getValue(OID cellOID);
160:
161: /**
162: * Gets the value of the cell instance in the specified column and row.
163: * @param index
164: * the row index of the cell.
165: * @param col
166: * the column index of the cell.
167: * @return
168: * the value of the cell or <code>null</code> if such a cell does not
169: * exist.
170: */
171: Variable getValue(OID index, int col);
172:
173: /**
174: * Adds a <code>MOChangeListener</code> that needs to be informed about
175: * state changes of this table.
176: * @param l
177: * a <code>MOChangeListener</code> instance.
178: */
179: void addMOChangeListener(MOChangeListener l);
180:
181: /**
182: * Removes a <code>MOChangeListener</code>
183: * @param l
184: * a <code>MOChangeListener</code> instance.
185: */
186: void removeMOChangeListener(MOChangeListener l);
187:
188: /**
189: * Adds a <code>MOTableRowListener</code> listener that needs to be informed
190: * about row changes (creation, addition, removal).
191: * @param l
192: * a <code>MOTableRowListener</code> instance.
193: */
194: void addMOTableRowListener(MOTableRowListener l);
195:
196: /**
197: * Removes <code>MOTableRowListener</code> instance.
198: * @param l
199: * a <code>MOTableRowListener</code> instance.
200: */
201: void removeMOTableRowListener(MOTableRowListener l);
202:
203: /**
204: * Creates a new row for this table with the supplied index and initial
205: * values. If one of the {@link MOTableRowListener} deny the row creation
206: * attempt then <code>null</code> will be returned.
207: * @param index
208: * the index OID of the new row.
209: * @param initialValues
210: * the initial values that should be assigned to the new row.
211: * @return
212: * the created <code>MOTableRow</code> instance or <code>null</code> if
213: * the row cannot be created.
214: */
215: MOTableRow createRow(OID index, Variable[] initialValues);
216:
217: /**
218: * Creates a new row for this table with the supplied index and
219: * default values. If one of the {@link MOTableRowListener}
220: * deny the row creation attempt then <code>null</code> will be returned.
221: * @param index
222: * the index OID of the new row.
223: * @return
224: * the created <code>MOTableRow</code> instance or <code>null</code> if
225: * the row cannot be created.
226: */
227: MOTableRow createRow(OID index);
228:
229: /**
230: * Adds the supplied row to the underlying table model and fires the
231: * appropriate {@link MOTableRowEvent}. Since this method is typically
232: * called during the commit phase of a SET request that creates a table,
233: * it should be avoided to return an error here. Instead error checking
234: * should be placed in the
235: * @param row
236: * the <code>MOTableRow</code> to add.
237: * @return
238: * <code>true</code> if the row has been added or <code>false</code>
239: * if it could not be added.
240: */
241: boolean addRow(MOTableRow row);
242:
243: /**
244: * Removes the row with the specified index and returns it if the operation
245: * was successful.
246: * @param index
247: * the index OID of the row to remove.
248: * @return
249: * the removed row or <code>null</code> if the row cannot be found or
250: * cannot be removed.
251: */
252: MOTableRow removeRow(OID index);
253: }
|