safearray.java

Very Nice library for using ActiveX controls directly from java without heavy knowledge of JNI, simp

/*
 * Copyright (c) 1999-2004 Sourceforge JACOB Project.
 * All rights reserved. Originator: Dan Adler (http://danadler.com).
 * Get more information about JACOB at http://sourceforge.net/projects/jacob-project
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
package com.jacob.com;

/**
 * This creates an array wrapper around Variant objects(?). Lookslike it
 * supports 1 and two dimensional arrays
 */
public class SafeArray extends JacobObject {
	int m_pV = 0;

	/**
	 * constructor
	 * 
	 */
	public SafeArray() {
	}

	/**
	 * constructor
	 * 
	 * @param vt
	 */
	public SafeArray(int vt) {
		init(vt, new int[] { 0 }, new int[] { -1 });
	}

	/**
	 * constructor
	 * 
	 * @param vt
	 * @param celems
	 */
	public SafeArray(int vt, int celems) {
		init(vt, new int[] { 0 }, new int[] { celems });
	}

	/**
	 * @param vt
	 * @param celems1
	 * @param celems2
	 */
	public SafeArray(int vt, int celems1, int celems2) {
		init(vt, new int[] { 0, 0 }, new int[] { celems1, celems2 });
	}

	/**
	 * constructor (needs more java doc)
	 * 
	 * With the addition of N-dimensional array support
	 * 
	 * You create an N-D SafeArray by: SafeArray sa = new
	 * SafeArray(Variant.VariantVariant, new int[] {0,0,0,0}, new int[]
	 * {4,4,4,4}); Where the 1st array is lower bounds and 2nd has the lengths
	 * of each dimension *
	 * 
	 * @param vt
	 * @param lbounds
	 * @param celems
	 */
	public SafeArray(int vt, int lbounds[], int celems[]) {
		init(vt, lbounds, celems);
	}

	/**
	 * convert a string to a VT_UI1 array
	 * 
	 * @param s
	 *            source string
	 */
	public SafeArray(String s) {
		char[] ca = s.toCharArray();
		init(Variant.VariantByte, new int[] { 0 }, new int[] { ca.length });
		fromCharArray(ca);
	}

	protected native void init(int vt, int lbounds[], int celems[]);

	/**
	 * not impl
	 * 
	 * @return 0
	 */
	public int getNumLocks() {
		return 0;
	}

	/**
	 * convert a VT_UI1 array to string
	 * 
	 * @return variant byte as a string
	 */
	public String asString() {
		if (getvt() != Variant.VariantByte) {
			return null;
		}
		char ja[] = toCharArray();
		return new String(ja);
	}

	public native Object clone();

	/**
	 * now private so only this object can asccess was: call this to explicitly
	 * release the com object before gc
	 * 
	 */
	private native void destroy();

	/**
	 * @return the Variant type
	 */
	public native int getvt();

	/*
	 * (non-Javadoc)
	 * 
	 * @see java.lang.Object#finalize()
	 */
	protected void finalize() {
		safeRelease();
	}

	/*
	 * (non-Javadoc)
	 * 
	 * @see com.jacob.com.JacobObject#safeRelease()
	 */
	public void safeRelease() {
		super.safeRelease();
		if (m_pV != 0) {
			destroy();
			m_pV = 0;
		} else {
			// looks like a double release
			if (isDebugEnabled()) {
				debug(this.getClass().getName() + ":" + this.hashCode()
						+ " double release");
			}
		}
	}

	/**
	 * Does anyone want to document this?
	 * 
	 * @param sa
	 */
	public native void reinit(SafeArray sa);

	/**
	 * Does anyone want to document this?
	 * 
	 * @param vt
	 *            the variant type?
	 */
	public native void reinterpretType(int vt);

	/**
	 * @return The lower bounds of the array?
	 */
	public native int getLBound();

	/**
	 * @param dim
	 *            the dimension we are checking in a multidimensional array
	 * @return The lower bounds of the array?
	 */
	public native int getLBound(int dim);

	/**
	 * @return The upper bounds of the array?
	 */
	public native int getUBound();

	/**
	 * @param dim
	 *            the dimension we are checking in a multidimensional array
	 * @return The upper bounds of the array?
	 */
	public native int getUBound(int dim);

	/**
	 * @return The number of dimensions in this array
	 */
	public native int getNumDim();

	/**
	 * @return The ??features of the array?
	 */
	public native int getFeatures();

	/**
	 * @return the size of each element?
	 */
	public native int getElemSize();

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromCharArray(char ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromIntArray(int ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromShortArray(short ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromDoubleArray(double ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromStringArray(String ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromByteArray(byte ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromFloatArray(float ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromBooleanArray(boolean ja[]);

	/**
	 * populate the safe array from the passed in array of data
	 * 
	 * @param ja
	 */
	public native void fromVariantArray(Variant ja[]);

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return char[] character array contained in this collection
	 */
	public native char[] toCharArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return int[] int array contained in this collection
	 */
	public native int[] toIntArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return short[] short array contained in this collection
	 */
	public native short[] toShortArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return double[] double array contained in this colleciton
	 */
	public native double[] toDoubleArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return String[] String array contained in this collecition
	 */
	public native String[] toStringArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return byte[] byte array contained in this collecition
	 */
	public native byte[] toByteArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return float[] array of float contained in this collection
	 */
	public native float[] toFloatArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return boolean[] array of booleans contained in this collection
	 */
	public native boolean[] toBooleanArray();

	/**
	 * Retrieves the data from the array cast to a Java data type
	 * 
	 * @return Variant[] array of variants contained in this collection
	 */
	public native Variant[] toVariantArray();

	/**
	 * char access
	 * 
	 * @param sa_idx
	 * @return single character rpeesentation
	 */
	public native char getChar(int sa_idx);

	/**
	 * char access
	 * 
	 * @param sa_idx1
	 * @param sa_idx2
	 * @return single character repesentation
	 */
	public native char getChar(int sa_idx1, int sa_idx2);

	/**
	 * char access
	 * 
	 * @param sa_idx
	 * @param c
	 */
	public native void setChar(int sa_idx, char c);

	/**
	 * char access
	 * 
	 * @param sa_idx1
	 * @param sa_idx2
	 * @param c
	 */
	public native void setChar(int sa_idx1, int sa_idx2, char c);

	/**
	 * char access
	 * 
	 * @param sa_idx
	 * @param nelems
	 * @param ja
	 * @param ja_start
	 */
	public native void getChars(int sa_idx, int nelems, char ja[], int ja_start);

	/**
	 * char access
	 * 
	 * @param sa_idx
	 * @param nelems
	 * @param ja
	 * @param ja_start
	 */
	public native void setChars(int sa_idx, int nelems, char ja[], int ja_start);

	/**
	 * get int from an single dimensional array
	 * 
	 * @param sa_idx
	 *            array index
	 * @return int stored in array
	 */
	public native int getInt(int sa_idx);

	/**
	 * get int from 2 dimensional array
	 * 
	 * @param sa_idx1
	 *            array index first dimension
	 * @param sa_idx2
	 *            array index of second dimension
	 * @return int stored in array
	 */
	public native int getInt(int sa_idx1, int sa_idx2);

	/**
	 * sets the int value of an element in a single dimensional array
	 * 
	 * @param sa_idx
	 *            index into the array
	 * @param c
	 *            the value to be set
	 */
	public native void setInt(int sa_idx, int c);

	/**
	 * sets the int value of a 2 dimensional array
	 * 
	 * @param sa_idx1
	 *            index on the first dimension
	 * @param sa_idx2
	 *            index on the second dimension
	 * @param c
	 *            the value to be set
	 */
	public native void setInt(int sa_idx1, int sa_idx2, int c);

	/**
	 * retrieves a group of ints from a single dimensional array
	 * 
	 * @param sa_idx
	 *            the index in the array to start the get
	 * @param nelems
	 *            number of elements to retrieve
	 * @param ja
	 *            the structure to be filled with the ints
	 * @param ja_start
	 *            the start point in the java int array to start filling
	 */
	public native void getInts(int sa_idx, int nelems, int ja[], int ja_start);

	/**
	 * sets a group of ints into a single dimensional array
	 * 
	 * @param sa_idx
	 *            the index of the start of the array to put into
	 * @param nelems
	 *            number of elements to be copied
	 * @param ja
	 *            the new int values to be put into the array
	 * @param ja_start
	 *            the start index in the array that we are copying into
	 *            SafeArray
	 */
	public native void setInts(int sa_idx, int nelems, int ja[], int ja_start);

	/**
	 * short access
	 * 
	 * @param sa_idx
	 * @return short stored in array
	 */
	public native short getShort(int sa_idx);

	/**
	 * short access
	 * 
	 * @param sa_idx1
	 * @param sa_idx2
	 * @return short stored in array
	 */
	public native short getShort(int sa_idx1, int sa_idx2);

	/**
	 * short access
	 * 
	 * @param sa_idx
	 * @param c
	 */
	public native void setShort(int sa_idx, short c);

	/**
	 * short access
	 * 
	 * @param sa_idx1
	 * @param sa_idx2
	 * @param c
	 */
	public native void setShort(int sa_idx1, int sa_idx2, short c);

	/**
	 * short access
	 * 
	 * @param sa_idx
	 * @param nelems
	 * @param ja
	 * @param ja_start
	 */
	public native void getShorts(int sa_idx, int nelems, short ja[],
			int ja_start);

	/**
	 * short access
	 * 
	 * @param sa_idx
	 * @param nelems
	 * @param ja
	 * @param ja_start
	 */
	public native void setShorts(int sa_idx, int nelems, short ja[],
			int ja_start);

	/**
	 * double access
	 * 
	 * @param sa_idx
	 * @return double stored in array
	 */
	public native double getDouble(int sa_idx);

	/**
	 * double access
	 * 
	 * @param sa_idx1