KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > smi > Variable


1 /*_############################################################################
2   _##
3   _## SNMP4J - Variable.java
4   _##
5   _## Copyright 2003-2007 Frank Fock and Jochen Katz (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 package org.snmp4j.smi;
22
23 import org.snmp4j.asn1.*;
24
25 /**
26  * The <code>Variable</code> interface defines common attributes of all SNMP
27  * variables.
28  * <p>
29  * Before version 1.8, Variable has been an abstract class which has been
30  * renamed to {@link AbstractVariable}.
31  *
32  * @author Frank Fock
33  * @version 1.8
34  * @since 1.8
35  */
36 public interface Variable extends Cloneable JavaDoc, Comparable JavaDoc, BERSerializable {
37
38   /**
39    * This definition of a serialVersionUID for the Variable interface
40    * has been made for backward compatibility with SNMP4J 1.7.x or earlier
41    * serialized Variable instances.
42    */
43   long serialVersionUID = 1395840752909725320L;
44
45   boolean equals(Object JavaDoc o);
46
47   int compareTo(Object JavaDoc o);
48
49   int hashCode();
50
51   /**
52    * Clones this variable. Cloning can be used by the SNMP4J API to better
53    * support concurrency by creating a immutable clone for internal processing.
54    *
55    * @return
56    * a new instance of this <code>Variable</code> with the same value.
57    */
58   Object JavaDoc clone();
59
60   /**
61    * Gets the ASN.1 syntax identifier value of this SNMP variable.
62    * @return
63    * an integer value < 128 for regular SMI objects and a value >= 128
64    * for exception values like noSuchObject, noSuchInstance, and
65    * endOfMibView.
66    */
67   int getSyntax();
68
69   /**
70    * Checks whether this variable represents an exception like
71    * noSuchObject, noSuchInstance, and endOfMibView.
72    * @return
73    * <code>true</code> if the syntax of this variable is an instance of
74    * <code>Null</code> and its syntax equals one of the following:
75    * <UL>
76    * <LI>{@link SMIConstants#EXCEPTION_NO_SUCH_OBJECT}</LI>
77    * <LI>{@link SMIConstants#EXCEPTION_NO_SUCH_INSTANCE}</LI>
78    * <LI>{@link SMIConstants#EXCEPTION_END_OF_MIB_VIEW}</LI>
79    * </UL>
80    */
81   boolean isException();
82
83   /**
84    * Gets a string representation of the variable.
85    * @return
86    * a string representation of the variable's value.
87    */
88   String JavaDoc toString();
89
90   /**
91    * Returns an integer representation of this variable if
92    * such a representation exists.
93    * @return
94    * an integer value (if the native representation of this variable
95    * would be a long, then the long value will be casted to int).
96    * @throws UnsupportedOperationException if an integer representation
97    * does not exists for this Variable.
98    */
99   int toInt();
100
101   /**
102    * Returns a long representation of this variable if
103    * such a representation exists.
104    * @return
105    * a long value.
106    * @throws UnsupportedOperationException if a long representation
107    * does not exists for this Variable.
108    */
109   long toLong();
110
111
112   /**
113    * Gets a textual description of this Variable.
114    * @return
115    * a textual description like 'Integer32'
116    * as used in the Structure of Management Information (SMI) modules.
117    * '?' is returned if the syntax is unknown.
118    */
119   String JavaDoc getSyntaxString();
120
121   /**
122    * Converts the value of this <code>Variable</code> to a (sub-)index
123    * value.
124    * @param impliedLength
125    * specifies if the sub-index has an implied length. This parameter applies
126    * to variable length variables only (e.g. {@link OctetString} and
127    * {@link OID}). For other variables it has no effect.
128    * @return
129    * an OID that represents this value as an (sub-)index.
130    * @throws UnsupportedOperationException
131    * if this variable cannot be used in an index.
132    */
133   OID toSubIndex(boolean impliedLength);
134
135   /**
136    * Sets the value of this <code>Variable</code> from the supplied (sub-)index.
137    * @param subIndex
138    * the sub-index OID.
139    * @param impliedLength
140    * specifies if the sub-index has an implied length. This parameter applies
141    * to variable length variables only (e.g. {@link OctetString} and
142    * {@link OID}). For other variables it has no effect.
143    * @throws UnsupportedOperationException
144    * if this variable cannot be used in an index.
145    */
146   void fromSubIndex(OID subIndex, boolean impliedLength);
147
148   /**
149    * Indicates whether this variable is dynamic. If a variable is dynamic,
150    * precautions have to be taken when a Variable is serialized using BER
151    * encoding, because between determining the length with
152    * {@link #getBERLength()} for encoding enclosing SEQUENCES and the actual
153    * encoding of the Variable itself with {@link #encodeBER} changes to the
154    * value need to be blocked by synchronization.
155    * <p>
156    * In order to ensure proper synchronization if a <code>Variable</code> is
157    * dynamic, modifications of the variables content need to synchronize on
158    * the <code>Variable</code> instance. This can be achieved for the standard
159    * SMI Variable implementations for example by
160    * <pre>
161    * public static modifyVariable(Integer32 variable, int value)
162    * synchronize(variable) {
163    * variable.setValue(value);
164    * }
165    * }
166    * </pre>
167    *
168    * @return
169    * <code>true</code> if the variable might change its value between
170    * two calls to {@link #getBERLength()} and {@link #encodeBER} and
171    * <code>false</code> if the value is immutable or if its value does
172    * not change while serialization because of measures taken by the
173    * implementor (i.e. variable cloning).
174    */
175   boolean isDynamic();
176 }
177
Popular Tags