Previous
Contents
Index
Next
| Package com.ms.com |
Previous |
Contents |
Index |
Next |
public final class SafeArray {
// Fields
protected int m_pSourceVariant;
// Constructors
public SafeArray(int vt)
public SafeArray(int vt, int celems)
public SafeArray(int vt, int celems1, int celems2)
public SafeArray(int vt, int lbounds[], int celems[])
public SafeArray(String s)
// Methods
public native int getPhysicalSafeArray()
public String toString()
public Object clone()
public int getNumDim()
public int getFeatures()
public int getElemSize()
public int getNumLocks()
public int getUBound()
public int getUBound(int dim)
public int getLBound()
public int getLBound(int dim)
public int getvt()
public native int getInt(int sa_idx)
public int getInt(int sa_idx1, int sa_idx2)
public void getInts(int sa_idx, int nelems, int ja[], int ja_start)
public int[] toIntArray()
public byte getByte(int sa_idx)
public byte getByte(int sa_idx1, int sa_idx2)
public void getBytes(int sa_idx, int nelems, byte ja[], int ja_start)
public byte[] toByteArray()
public char getChar(int sa_idx)
public char getChar(int sa_idx1, int sa_idx2)
public void getChars(int sa_idx, int nelems, char ja[], int ja_start)
public char[] toCharArray()
public short getShort(int sa_idx)
public short getShort(int sa_idx1, int sa_idx2)
public void getShorts(int sa_idx, int nelems, short ja[], int ja_start)
public short[] toShortArray()
public native float getFloat(int sa_idx)
public float getFloat(int sa_idx1, int sa_idx2)
public void getFloats(int sa_idx, int nelems, float ja[], int ja_start)
public float[] toFloatArray()
public native double getDouble(int sa_idx)
public double getDouble(int sa_idx1, int sa_idx2)
public void getDoubles(int sa_idx, int nelems, double ja[], int ja_start)
public double[] toDoubleArray()
public native boolean getBoolean(int sa_idx)
public boolean getBoolean(int sa_idx1, int sa_idx2)
public void getBooleans(int sa_idx, int nelems, boolean ja[], int ja_start)
public boolean[] toBooleanArray()
public String getString(int sa_idx)
public String getString(int sa_idx1, int sa_idx2)
public void getStrings(int sa_idx, int nelems, String ja[], int ja_start)
public String[] toStringArray()
public Variant getVariant(int sa_idx)
public Variant getVariant(int sa_idx1, int sa_idx2)
public void getVariants(int sa_idx, int nelems, Variant ja[], int ja_start)
public Variant[] toVariantArray()
public native void setInt(int idx, int val)
public void setInt(int idx1, int idx2, int val)
public void setInts(int sa_idx, int nelems, int ja[], int ja_start)
public void fromIntArray(int ja[])
public void setByte(int idx, byte val)
public void setByte(int idx1, int idx2, byte val)
public void setBytes(int sa_idx, int nelems, byte ja[], int ja_start)
public void fromByteArray(byte ja[])
public void setChar(int idx, char val)
public void setChar(int idx1, int idx2, char val)
public void setChars(int sa_idx, int nelems, char ja[], int ja_start)
public void fromCharArray(char ja[])
public void setShort(int idx, short val)
public void setShort(int idx1, int idx2, short val)
public void setShorts(int sa_idx, int nelems, short ja[], int ja_start)
public void fromShortArray(short ja[])
public native void setFloat(int idx, float val)
public void setFloat(int idx1, int idx2, float val)
public void setFloats(int sa_idx, int nelems, float ja[], int ja_start)
public void fromFloatArray(float ja[])
public native void setDouble(int idx, double val)
public void setDouble(int idx1, int idx2, double val)
public void setDoubles(int sa_idx, int nelems, double ja[], int ja_start)
public void fromDoubleArray(double ja[])
public native void setBoolean(int idx, boolean val)
public void setBoolean(int idx1, int idx2, boolean val)
public void setBooleans(int sa_idx, int nelems, boolean ja[], int ja_start)
public void fromBooleanArray(boolean ja[])
public void setString(int idx, String val)
public void setString(int idx1, int idx2, String val)
public void setStrings(int sa_idx, int nelems, String ja[], int ja_start)
public void fromStringArray(String ja[])
public void setVariant(int idx, Variant val)
public void setVariant(int idx1, int idx2, Variant val)
public void setVariants(int sa_idx, int nelems, Variant ja[], int ja_start)
public void fromVariantArray(Variant ja[])
public native String asString()
public void destroy()
public void reinterpretType(int vt)
protected void finalize()
}
The SafeArray class wraps an ActiveX Automation SAFEARRAY data structure. This class is used to bridge Java with Automation objects.
SafeArrays wrap pointers to native SAFEARRAYs. They do not duplicate the array data in Java form. This minimizes translation overhead, at the cost of imposing extra rules on SafeArray usage. Because SAFEARRAYs do not have reference counts, the process of creating and destroying SAFEARRAYs cannot be made completely transparent to the Java programmer. Because of this, the SafeArray class can only be loaded by a trusted applet.
The rules are simple but must be followed:
1. A Java method which receives a SafeArray as a parameter may use that SafeArray only for the duration of the method call. If a longer-term copy is needed, the SafeArray must be converted to a Java array or the clone method must be used to create an independent copy.
2. If a Java method returns a SafeArray, that SafeArray is considered owned by the caller and the Java method should no longer use the SafeArray instance. The simplest way to follow this rule is for the called method to construct a new SafeArray object each time it is called.
In addition to maintain a pointer to a native SAFEARRAY, the SafeArray instance maintains separately the exact VarType of the SAFEARRAY elements. The VarType is determined either via an argument to the SafeArray constructor, or is bound into the .class file via JCOM.
The system class com.ms.com.Variant defines public constants (Variant.VariantXXX) for all of the valid VarTypes. The VariantByref and VariantArray modifiers may not be set in an element vartype.
(Note for JavaTLB users: the JavaTLB tool emits an older class file format which does not provide the exact VarType. This means in some cases, the SAFEARRAY data structure will not provide enough information to determine an exact VarType. In this case, the Java runtime will choose a default VarType based on the following heuristics:
SAFEARRAY's of type VT_BSTR, VT_UNKNOWN, VT_DISPATCH or VT_VARIANT are explicitly flagged as such in the SAFEARRAY data structure; thus, these will always marshal correctly.
Otherwise, SAFEARRAYs whose element size is 1 is presumed to be type VT_UI1. If the size is 2, VT_I2. If the size is 4, VT_I4. If the size is 8, VT_R8. Otherwise, a ClassCastException is thrown. )
public SafeArray(int vt)Creates a SafeArray instance that wraps the NULL pointer. The main purpose is to pass NULL to COM methods that accept SAFEARRAYs.
The element vartype should be one of the Variant.VariantXXX constants. Neither the VariantArray nor VariantByref may be set.
Parameter Description vt the element vartype
public SafeArray(int vt, int celems)Creates a one-dimensional SafeArray. Valid indices range from 0 (inclusive) to celems (exclusive.) Note that this convention follows the C convention of indicating the number of elements rather than the Visual Basic convention of indicating the upper bound.
The element vartype should be one of the Variant.VariantXXX constants. Neither the VariantArray nor VariantByref may be set.
Parameter Description vt the element vartype celems number of elements
public SafeArray(int vt, int celems1, int celems2)Creates a two-dimensional SafeArray. The constructor follows the C convention of indicating the number of elements rather than the Visual Basic convention of indicating the upper bound.
The expression:
new SafeArray(Variant.VariantVariant, 21, 11); is equivalent to the Visual Basic declaration:
Option Base 0Dim A(20, 10)The element vartype should be one of the Variant.VariantXXX constants. Neither the VariantArray nor VariantByref may be set.
Parameter Description vt the element vartype celems number of elements
public SafeArray(int vt, int lbounds[], int celems[])Creates a SafeArray of arbitrary shape. The lbounds array indicates the lower bound for each dimension. The celems parameter, which must be the same length as lbounds, gives the number of elements. lbounds may be null, in which case, all the lower bounds default to 0.
The code:
int lbounds[] = {-1,-3, -4}; int celems[] = {10, 20, 30}; SafeArray A = new SafeArray(Variant.VariantVariant, lbounds, celems);is equivalent the Visual Basic declaration:
Dim A(-1 To 8, -3 To 16, -4 To 25)The element vartype should be one of the Variant.VariantXXX constants. Neither the VariantArray nor VariantByref may be set.
Parameter Description vt the element vartype lbounds the lower bounds for each dimension celems the number of elements in each dimension
public SafeArray(String s)Creates a VT_UI1 SafeArray from a string. Each character of the string occupies two elements of the array to form a single Unicode character. The array is not null terminated. This constructor corresponds to the standard Automation conversion from VT_BSTR to VT_ARRAY|VT_UI1.
Parameter Description s provides initial contents.
public native int getPhysicalSafeArray()Returns the linear address of the actual SAFEARRAY, packaged up as a Java integer. This method is provided to aid in debugging only. There are no useful operations (other than displaying) that can be done with this value from Java.
Return Value:
Returns the linear address of the represented SAFEARRAY.
public native String asString()Converts a VT_UI1 SafeArray to a string. This corresponds to the VariantChangeType conversion from VT_ARRAY|VT_UI1 to VT_BSTR.
Return Value:
Returns the converted value.
public Object clone()Creates an exact and independent duplicate of the SafeArray. This is a wrapper around the Win32 SafeArrayCopy api.
Return Value:
Returns a new SafeArray containing an independent duplicate.
public void destroy()Forcefully invokes the Win32 api SafeArrayDestroy. This is a potentially dangerous routine and should be used with extreme caution. It is not necessary to invoke this method when following standard COM memory ownership rules as the Java/COM integration subsystem and the Java garbage collector will work together to ensure correct disposal of SafeArrays.
public void reinterpretType(int vt)Forces SafeArray to interpret elements as another vartype.
Return Value:
No return value.
Parameter Description vt The element vartype.
protected void finalize()
public void fromBooleanArray(boolean ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: if you are modifying a large number of elements, it may be more efficient to use fromCharArray() rather than fromBooleanArray(). This is because boolean SafeArrays use two bytes per element, and thus the fromBooleanArray() method cannot optimize itself to a memcpy.
Parameter Description ja Java array containing the elements to set.
public void fromByteArray(byte ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description ja Java array containing the elements to set.
public void fromCharArray(char ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description ja Java array containing the elements to set.
public void fromDoubleArray(double ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description ja Java array containing the elements to set.
public void fromFloatArray(float ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description ja Java array containing the elements to set.
public void fromIntArray(int ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description ja Java array containing the elements to set.
public void fromShortArray(short ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description ja Java array containing the elements to set.
public void fromStringArray(String ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Parameter Description ja Java array containing the elements to set.
public void fromVariantArray(Variant ja[])Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is initialized from element 0 of the Java array.
If the Java array is shorter than the number of SafeArray elements, the leftover SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is SafeArray of Variants.
Parameter Description ja Java array containing the elements to set.
public native boolean getBoolean(int sa_idx)Extracts an element of a one-dimensional SafeArray as a boolean. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public boolean getBoolean(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as an boolean. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getBooleans(int sa_idx, int nelems, boolean ja[], int ja_start)Extracts multiple elements as booleans. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: if you are extracting a large number of elements, it may be more efficient to use getChars() rather than getBooleans(). This is because boolean SafeArrays use two bytes per element, and thus the getBooleans() method cannot optimize itself to a memcpy.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public byte getByte(int sa_idx)Extracts an element of a one-dimensional SafeArray as a byte. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public byte getByte(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as a byte. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getBytes(int sa_idx, int nelems, byte ja[], int ja_start)Extracts multiple elements as bytes. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public char getChar(int sa_idx)Extracts an element of a one-dimensional SafeArray as a char. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public char getChar(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as a char. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getChars(int sa_idx, int nelems, char ja[], int ja_start)Extracts multiple elements as chars. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public native double getDouble(int sa_idx)Extracts an element of a one-dimensional SafeArray as a double. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public double getDouble(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as an double. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getDoubles(int sa_idx, int nelems, double ja[], int ja_start)Extracts multiple elements as doubles. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public int getElemSize()Returns the size, in bytes, of a single element.
Return Value:
Returns size in bytes of a single element.
public int getFeatures()Returns contents of the fFeatures bitmask. This bitmask (defined as part of the Ole SAFEARRAY data structure provides various information about the SAFEARRAY.
Return Value:
Returns the fFeatures field.
public native float getFloat(int sa_idx)Extracts an element of a one-dimensional SafeArray as a float. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public float getFloat(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as an float. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getFloats(int sa_idx, int nelems, float ja[], int ja_start)Extracts multiple elements as floats. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public native int getInt(int sa_idx)Extracts an element of a one-dimensional SafeArray as an int. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public int getInt(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as an int. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getInts(int sa_idx, int nelems, int ja[], int ja_start)Extracts multiple elements as ints. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public int getLBound()Returns the smallest valid index of the array's first dimension. Identical to the Visual Basic LBound function.
Return Value:
Returns smallest valid index.
public int getLBound(int dim)Returns the smallest valid index of an arbitrary dimension. Dimensions are numbered starting with 1. Identical to the Visual Basic LBound function.
Return Value:
Returns smallest valid index.
public int getNumDim()Returns the number of dimensions.
Return Value:
Returns the number of dimensions. 1 for single-dimensional, etc.
public int getNumLocks()Returns the number of outstanding locks on the SafeArray. This value will normally be zero and is only useful for debugging purposes.
Return Value:
Returns outstanding lock count.
public short getShort(int sa_idx)Extracts a element of a one-dimensional SafeArray as a short. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public short getShort(int sa_idx1, int sa_idx2)Extracts a element of a two-dimensional array as an short. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getShorts(int sa_idx, int nelems, short ja[], int ja_start)Extracts multiple elements as shorts. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public String getString(int sa_idx)Extracts an element of a one-dimensional SafeArray as a String. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public String getString(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as an String. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getStrings(int sa_idx, int nelems, String ja[], int ja_start)Extracts multiple elements as Strings. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public int getUBound()Returns the largest valid index of the array's first dimension. Identical to the Visual Basic UBound function.
Return Value:
Returns largest valid index.
public int getUBound(int dim)Returns the largest valid index of an arbitrary dimension. Dimensions are numbered starting with 1. Identical to the Visual Basic UBound function.
Return Value:
Returns largest valid index.
public Variant getVariant(int sa_idx)Extracts an element of a one-dimensional SafeArray as a Variant. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, then coerce the Variant. This is true even if the SafeArray is a SafeArray of Variant.
Return Value:
Returns the converted element value
Parameter Description sa_idx element index, ranging from LBound() to UBound()
public Variant getVariant(int sa_idx1, int sa_idx2)Extracts an element of a two-dimensional array as an Variant. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the SafeArray element cannot be converted to the correct type using the Win32 api VariantChangeType().
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, then coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.
Return Value:
Returns the converted element value
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2)
public void getVariants(int sa_idx, int nelems, Variant ja[], int ja_start)Extracts multiple elements as Variants. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, then coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.
Parameter Description sa_idx index of first element to retrieve (always zero-based) nelems number of elements to retrieve ja java array which receives the values ja_start index of first element to receive a value in ja
public int getvt()Returns the vartype of the SafeArray elements. This corresponds to one of the public constants com.ms.com.VariantXXX. Note: If JavaTLB is used to generate the Java method information that passes a SafeArray from COM to Java, the VarType may be inexact although the element size will always be correct. JavaTLB has been superceded by the JCOM tool which binds the exact VarType into the .class file.
Return Value:
Returns the element vartype
public native void setBoolean(int idx, boolean val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setBoolean(int idx1, int idx2, boolean val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setBooleans(int sa_idx, int nelems, boolean ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: if you are modifying a large number of elements, it may be more efficient to use setChars() rather than setBooleans(). This is because boolean SafeArrays use two bytes per element, and thus the setBooleans() method cannot optimize itself to a memcpy.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public void setByte(int idx, byte val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setByte(int idx1, int idx2, byte val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setBytes(int sa_idx, int nelems, byte ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public void setChar(int idx, char val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setChar(int idx1, int idx2, char val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setChars(int sa_idx, int nelems, char ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public native void setDouble(int idx, double val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setDouble(int idx1, int idx2, double val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setDoubles(int sa_idx, int nelems, double ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public native void setFloat(int idx, float val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setFloat(int idx1, int idx2, float val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setFloats(int sa_idx, int nelems, float ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public native void setInt(int idx, int val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setInt(int idx1, int idx2, int val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setInts(int sa_idx, int nelems, int ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public void setShort(int idx, short val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setShort(int idx1, int idx2, short val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setShorts(int sa_idx, int nelems, short ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public void setString(int idx, String val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setString(int idx1, int idx2, String val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setStrings(int sa_idx, int nelems, String ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public void setVariant(int idx, Variant val)Sets an element of a one-dimensional SafeArray. A IndexOutOfBoundsException is thrown if the array is not one-dimensional, or if sa_idx lies outside the defined range (LBound()..UBound()). A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is SafeArray of Variants.
Parameter Description sa_idx element index, ranging from LBound() to UBound() val the new element value
public void setVariant(int idx1, int idx2, Variant val)Sets an element of a two-dimensional array. A IndexOutOfBoundsException is thrown if the array is not two-dimensional, or if either index lies outside the defined range. A ClassCastException is thrown if the Java value cannot be converted to the SafeArray element type using the Win32 api VariantChangeType().
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is SafeArray of Variants.
Parameter Description sa_idx1 first element index, ranging from LBound(1) to UBound(1) sa_idx2 first element index, ranging from LBound(2) to UBound(2) val the new element value
public void setVariants(int sa_idx, int nelems, Variant ja[], int ja_start)Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is assigned index 0 for the purposes of this method.
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is SafeArray of Variants.
Parameter Description sa_idx index of first element to set (always zero-based) nelems number of elements to set ja java array which provides the values ja_start index of first element to use in ja
public boolean[] toBooleanArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: if you are extracting a large number of elements, it may be more efficient to use toCharArray() rather than toBooleanArray(). This is because boolean SafeArrays use two bytes per element, and thus the toBooleanArray() method cannot optimize itself to a memcpy.
Return Value:
Returns the flattened contents of the array.
public byte[] toByteArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Return Value:
Returns the flattened contents of the array.
public char[] toCharArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Return Value:
Returns the flattened contents of the array.
public double[] toDoubleArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Return Value:
Returns the flattened contents of the array.
public float[] toFloatArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Return Value:
Returns the flattened contents of the array.
public int[] toIntArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Return Value:
Returns the flattened contents of the array.
public short[] toShortArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though this method attempts all the usual type conversions, the best performance will be achieved if the element size of the source and destination arrays match exactly. The method will optimize to a straight memcpy in this case.
Return Value:
Returns the flattened contents of the array.
public String toString()Defines the printed representation of a SafeArray.
Return Value:
Returns the printed representation.
public String[] toStringArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Return Value:
Returns the flattened contents of the array.
public Variant[] toVariantArray()Converts entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the LBound() is, the first element is stored in element 0 of the Java array.
Performance tip: Though the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, then coerce the Variant. This is true even if the SafeArray is SafeArray of Variants.
Return Value:
Returns the flattened contents of the array.
© 1997 Microsoft Corporation. All rights reserved. Legal Notices.