KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > agent > mo > MOTable


1 /*_############################################################################
2   _##
3   _## SNMP4J-Agent - MOTable.java
4   _##
5   _## Copyright (C) 2005-2007 Frank Fock (SNMP4J.org)
6   _##
7   _## Licensed under the Apache License, Version 2.0 (the "License");
8   _## you may not use this file except in compliance with the License.
9   _## You may obtain a copy of the License at
10   _##
11   _## http://www.apache.org/licenses/LICENSE-2.0
12   _##
13   _## Unless required by applicable law or agreed to in writing, software
14   _## distributed under the License is distributed on an "AS IS" BASIS,
15   _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   _## See the License for the specific language governing permissions and
17   _## limitations under the License.
18   _##
19   _##########################################################################*/

20
21
22 package org.snmp4j.agent.mo;
23
24 import org.snmp4j.smi.OID;
25 import org.snmp4j.agent.MOScope;
26 import org.snmp4j.smi.Variable;
27 import org.snmp4j.agent.ManagedObject;
28
29 /**
30  * The <code>MOTable</code> interface describes SNMP conceptual tables.
31  * In general, a conceptual table can be implemented in two different ways:
32  * <ul>
33  * <li>For large tables, a virtual table model is best suited where rows are
34  * created on behalf of a request only. The instrumentation directly propagates
35  * data to the managed objects without holding the data in a table model.</li>
36  * <li>For small or medium size tables, holding the data in (non virtual) table
37  * model provides data caching and decoupling of the instrumentation.</li>
38  * </ul>
39  * @author Frank Fock
40  * @version 1.0
41  */

42 public interface MOTable extends ManagedObject {
43
44   /**
45    * Finds the object identifier of the first object instance in the specified
46    * range.
47    * @param range
48    * a <code>MOScope</code> specifying the search range.
49    * @return
50    * the OID of the lexicographic first instance in the search range or
51    * <code>null</code> if no such instance exists.
52    */

53   OID find(MOScope range);
54
55   /**
56    * Returns the zero based column index for the specified column
57    * sub-identifier.
58    * @param id
59    * a column sub-identifier (normally one based) as defined in the MIB
60    * specification.
61    * @return
62    * a value greater or equal to zero denoting the column index
63    * of the column associated with <code>id</code>. The column index
64    * points into the column array returned by {@link #getColumns}.
65    * A value less than zero indicates that such a column does not exists
66    * currently but could be inserted at the <code>(-n)-1</code> position
67    * if <code>n</code> is the returned value.
68    */

69   int getColumnIndex(int id);
70
71   /**
72    * Gets the column definitions for this table.
73    * @return
74    * an array with the column definitions of this table.
75    */

76   MOColumn[] getColumns();
77
78   /**
79    * Gets the column definition for the specified column.
80    * @param index
81    * the (zero-based) column index.
82    * @return
83    * a <code>MOColumn</code> instance describing the attributes of requested
84    * column.
85    */

86   MOColumn getColumn(int index);
87
88   /**
89    * Returns a <code>MOTableCellInfo</code> instance for the supplied
90    * cell OID. The returned object contains the index, column index, and
91    * column ID of the specified cell, if available.
92    * @param oid
93    * cell instance OID.
94    * @return
95    * a <code>MOTableCellInfo</code> instance with the index, column index
96    * and column ID of the specified cell if available.
97    */

98   MOTableCellInfo getCellInfo(OID oid);
99
100   /**
101    * Returns the number of columns in this table.
102    * @return
103    * the column count.
104    */

105   int getColumnCount();
106
107   /**
108    * Gets the index definition of this table.
109    *
110    * @return
111    * a MOTableIndex instance containing the sub-index definitions for this
112    * table.
113    */

114   MOTableIndex getIndexDef();
115
116   /**
117    * Returns the index part of a column instance identifier of this table.
118    * @param instanceIdentifier
119    * the OID of a column instance. The returned result is undefined, when
120    * this OID is not a column instance OID.
121    * @return
122    * an OID representing the index OID of the row identified by the
123    * <code>instanceIdentifier</code> column instance OID.
124    */

125   OID getIndexPart(OID instanceIdentifier);
126
127   /**
128    * Gets the table model of this table.
129    * @return
130    * a MOTableModel instance.
131    */

132   MOTableModel getModel();
133
134   /**
135    * Returns the OID of the table entry.
136    * @return
137    * a table entry OID (including the .1 suffix).
138    */

139   OID getOID();
140
141   /**
142    * Returns an array of variables where each variable corresponds to the
143    * column with the same index. If a column has a default value, the returned
144    * variable is not <code>null</code> and contains that default value.
145    *
146    * @return
147    * the default variables for a newly created row as an array of
148    * <code>Variable</code> instances.
149    */

150   Variable[] getDefaultValues();
151
152   /**
153    * Gets the value of the cell instance with the specified instance OID.
154    * @param cellOID
155    * the instance OID of the requested cell.
156    * @return
157    * the value of the cell or <code>null</code> if such a cell does not
158    * exist.
159    */

160   Variable getValue(OID cellOID);
161
162   /**
163    * Gets the value of the cell instance in the specified column and row.
164    * @param index
165    * the row index of the cell.
166    * @param col
167    * the column index of the cell.
168    * @return
169    * the value of the cell or <code>null</code> if such a cell does not
170    * exist.
171    */

172   Variable getValue(OID index, int col);
173
174   /**
175    * Adds a <code>MOChangeListener</code> that needs to be informed about
176    * state changes of this table.
177    * @param l
178    * a <code>MOChangeListener</code> instance.
179    */

180   void addMOChangeListener(MOChangeListener l);
181
182   /**
183    * Removes a <code>MOChangeListener</code>
184    * @param l
185    * a <code>MOChangeListener</code> instance.
186    */

187   void removeMOChangeListener(MOChangeListener l);
188
189   /**
190    * Adds a <code>MOTableRowListener</code> listener that needs to be informed
191    * about row changes (creation, addition, removal).
192    * @param l
193    * a <code>MOTableRowListener</code> instance.
194    */

195   void addMOTableRowListener(MOTableRowListener l);
196
197   /**
198    * Removes <code>MOTableRowListener</code> instance.
199    * @param l
200    * a <code>MOTableRowListener</code> instance.
201    */

202   void removeMOTableRowListener(MOTableRowListener l);
203
204   /**
205    * Creates a new row for this table with the supplied index and initial
206    * values. If one of the {@link MOTableRowListener} deny the row creation
207    * attempt then <code>null</code> will be returned.
208    * @param index
209    * the index OID of the new row.
210    * @param initialValues
211    * the initial values that should be assigned to the new row.
212    * @return
213    * the created <code>MOTableRow</code> instance or <code>null</code> if
214    * the row cannot be created.
215    */

216   MOTableRow createRow(OID index, Variable[] initialValues);
217
218   /**
219    * Creates a new row for this table with the supplied index and
220    * default values. If one of the {@link MOTableRowListener}
221    * deny the row creation attempt then <code>null</code> will be returned.
222    * @param index
223    * the index OID of the new row.
224    * @return
225    * the created <code>MOTableRow</code> instance or <code>null</code> if
226    * the row cannot be created.
227    */

228   MOTableRow createRow(OID index);
229
230   /**
231    * Adds the supplied row to the underlying table model and fires the
232    * appropriate {@link MOTableRowEvent}. Since this method is typically
233    * called during the commit phase of a SET request that creates a table,
234    * it should be avoided to return an error here. Instead error checking
235    * should be placed in the
236    * @param row
237    * the <code>MOTableRow</code> to add.
238    * @return
239    * <code>true</code> if the row has been added or <code>false</code>
240    * if it could not be added.
241    */

242   boolean addRow(MOTableRow row);
243
244   /**
245    * Removes the row with the specified index and returns it if the operation
246    * was successful.
247    * @param index
248    * the index OID of the row to remove.
249    * @return
250    * the removed row or <code>null</code> if the row cannot be found or
251    * cannot be removed.
252    */

253   MOTableRow removeRow(OID index);
254 }
255
Popular Tags