com.almworks.sqlite4java
Class SQLiteLongArray

java.lang.Object
  extended by com.almworks.sqlite4java.SQLiteLongArray

public class SQLiteLongArray
extends java.lang.Object

SQLiteLongArray wraps a virtual table handle, created with SQLiteConnection.createArray(java.lang.String, boolean) (sqlite3_intarray* in test_intarray.h). Use methods of this class to set the array's contents (maybe several times), and dispose it when done.

Like with other classes, the methods are confined to the thread that opened SQLiteConnection, unless stated otherwise.

The virtual array table has a single column named value.

Values must not be unique or come in any order - they are not a primary key, nor is there an index over them. That also means searching through the virtual array table is done with a full scan, so be careful with the performance.

Author:
Igor Sereda

Method Summary
 SQLiteLongArray bind(long[] values)
          Fills virtual array table with values from a Java array.
 SQLiteLongArray bind(long[] values, int offset, int length)
          Fills virtual array table with values from the specified portion of a Java array.
 void dispose()
          Disposes this instance, making it unusable and freeing the resources.
 java.lang.String getName()
          Returns the name of the virtual table, which should be used in SQL.
 boolean isDisposed()
          Returns true if the instance is disposed and cannot be used.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getName

public java.lang.String getName()
Returns the name of the virtual table, which should be used in SQL.

This method is thread-safe.

Returns:
virtual table's name, not null

isDisposed

public boolean isDisposed()
Returns true if the instance is disposed and cannot be used. If the array was cached, it may still remain and be addressable through SQL, but it may contain no data or any irrelevant data (as defined by the current user of the instance).

Returns:
true if the instance is unusable

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

dispose

public void dispose()
Disposes this instance, making it unusable and freeing the resources. If the array table is cached, then it is unbound from values (emptied) and returned to the cache. If the array table is not cached, it is deleted from the database.

This method is partially thread-safe. When called not from the confining thread, the exception will not be thrown, but the method will do nothing.

Calling dispose() second time has no effect.

Calling bind(long[], int, int) after instance has been disposed would result in exception.


bind

public SQLiteLongArray bind(long[] values,
                            int offset,
                            int length)
                     throws SQLiteException
Fills virtual array table with values from the specified portion of a Java array.

Values are copied into a native non-heap memory, so the array can be used for other purposes after calling this method.

Values need not to be unique or come in any specific order.

Memory, allocated for the virtual array table, is freed on the next call to bind, when array instance is disposed, or when database is closed.

Parameters:
values - array of the values to bind, may be null if length == 0
offset - the index of an element to be bound as the first row
length - the number of values to bind, if set to 0 then the virtual array table will be empty
Returns:
this instance
Throws:
SQLiteException - if this instance has been disposed or problem occurs on the underlying layer
java.lang.ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within values array
java.lang.NullPointerException - if values is null and length is not zero

bind

public SQLiteLongArray bind(long[] values)
                     throws SQLiteException
Fills virtual array table with values from a Java array. This is a convenience method for bind(long[], int, int).

Parameters:
values - array of the values to bind, if null - bind to an empty array
Returns:
this instance
Throws:
SQLiteException - if this instance has been disposed or problem occurs on the underlying layer
java.lang.ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within values array
java.lang.NullPointerException - if values is null and length is not zero