com.almworks.sqlite4java
Class SQLiteLongArray

java.lang.Object
  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). 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 with INTEGER affinity.

If you bind ordered and/or unique values to the array, it may greatly improve performance if the underlying code knows about that fact. See bind(long[], int, int, boolean, boolean) method for details.

Author:

Igor Sereda

Method Summary

SQLiteLongArray	bind(long... values) Fills virtual array table with values from a Java array.
SQLiteLongArray	bind(long[] values, boolean ordered, boolean unique) 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 a Java array.
SQLiteLongArray	bind(long[] values, int offset, int length, boolean ordered, boolean unique) 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, boolean, boolean) after instance has been disposed would result in exception.

bind

public SQLiteLongArray bind(long[] values,
                            int offset,
                            int length,
                            boolean ordered,
                            boolean unique)
                     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.

If ordered and unique are false, values need not to be unique or come in any specific order. If ordered is true, then the caller guarantees that the values come in ascending order. If unique is true, then the values are guaranteed to be unique. Failing those guarantees would result in incorrect search results.

Passing ordered and/or unique values allows SQLite to optimize search and access to the array.

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

ordered - if true, the values within the specified by offset and length region are in non-strict ascending order

unique - if true, the values within the specified by offset and length region are not repeating

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,
                            int offset,
                            int length)
                     throws SQLiteException

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

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, boolean, boolean).

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

bind

public SQLiteLongArray bind(long[] values,
                            boolean ordered,
                            boolean unique)
                     throws SQLiteException

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

Parameters:

values - array of the values to bind, if null - bind to an empty array

ordered - if true, the values within the specified by offset and length region are in non-strict ascending order

unique - if true, the values within the specified by offset and length region are not repeating

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