Package net.carcdr.ycrdt.jni

Class JniYArray

java.lang.Object

net.carcdr.ycrdt.jni.JniYArray

All Implemented Interfaces:

AutoCloseable, net.carcdr.ycrdt.YArray

public class JniYArray
extends Object
implements net.carcdr.ycrdt.YArray

YArray represents a collaborative array type in a Y-CRDT document.

YArray provides efficient collaborative array operations with automatic conflict resolution. Multiple users can modify the same array simultaneously, and changes will be merged automatically using CRDT algorithms.

This class implements Closeable and should be used with try-with-resources to ensure proper cleanup of native resources.

Example usage:

 try (YDoc doc = new JniYDoc();
      YArray array = doc.getArray("myarray")) {
     array.pushString("Hello");
     array.pushDouble(42.0);
     array.insertString(1, "World");
     System.out.println(array.toJson()); // ["Hello","World",42.0]
 }
 

See Also:

• YDoc

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this YArray and releases native resources.
JniYDoc	getDoc(int index)	Gets a YDoc subdocument at the specified index.
JniYDoc	getDoc(net.carcdr.ycrdt.YTransaction txn, int index)	Gets a YDoc subdocument at the specified index using an existing transaction.
double	getDouble(int index)	Gets a double value at the specified index.
double	getDouble(net.carcdr.ycrdt.YTransaction txn, int index)	Gets a double value at the specified index using an existing transaction.
String	getString(int index)	Gets a string value at the specified index.
String	getString(net.carcdr.ycrdt.YTransaction txn, int index)	Gets a string value at the specified index using an existing transaction.
void	insertDoc(int index, net.carcdr.ycrdt.YDoc subdoc)	Inserts a YDoc subdocument at the specified index (creates implicit transaction).
void	insertDoc(net.carcdr.ycrdt.YTransaction txn, int index, net.carcdr.ycrdt.YDoc subdoc)	Inserts a YDoc subdocument at the specified index within an existing transaction.
void	insertDouble(int index, double value)	Inserts a double value at the specified index (creates implicit transaction).
void	insertDouble(net.carcdr.ycrdt.YTransaction txn, int index, double value)	Inserts a double value at the specified index within an existing transaction.
void	insertString(int index, String value)	Inserts a string value at the specified index (creates implicit transaction).
void	insertString(net.carcdr.ycrdt.YTransaction txn, int index, String value)	Inserts a string value at the specified index within an existing transaction.
boolean	isClosed()	Checks if this YArray has been closed.
int	length()	Returns the length of the array.
int	length(net.carcdr.ycrdt.YTransaction txn)	Returns the length of the array using an existing transaction.
net.carcdr.ycrdt.YSubscription	observe(net.carcdr.ycrdt.YObserver observer)	Registers an observer to be notified when this array changes.
void	pushDoc(net.carcdr.ycrdt.YDoc subdoc)	Appends a YDoc subdocument to the end of the array (creates implicit transaction).
void	pushDoc(net.carcdr.ycrdt.YTransaction txn, net.carcdr.ycrdt.YDoc subdoc)	Appends a YDoc subdocument to the end of the array within an existing transaction.
void	pushDouble(double value)	Appends a double value to the end of the array (creates implicit transaction).
void	pushDouble(net.carcdr.ycrdt.YTransaction txn, double value)	Appends a double value to the end of the array within an existing transaction.
void	pushString(String value)	Appends a string value to the end of the array (creates implicit transaction).
void	pushString(net.carcdr.ycrdt.YTransaction txn, String value)	Appends a string value to the end of the array within an existing transaction.
void	remove(int index, int length)	Removes a range of elements from the array (creates implicit transaction).
void	remove(net.carcdr.ycrdt.YTransaction txn, int index, int length)	Removes a range of elements from the array within an existing transaction.
String	toJson()	Returns a JSON string representation of the array.
String	toJson(net.carcdr.ycrdt.YTransaction txn)	Returns a JSON string representation of the array using an existing transaction.
void	unobserveById(long subscriptionId)	Unregisters an observer by its subscription ID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

length

public int length()

Returns the length of the array.

Specified by:

length in interface net.carcdr.ycrdt.YArray

Returns:

The number of elements in the array

Throws:

IllegalStateException - if the array has been closed

length

public int length(net.carcdr.ycrdt.YTransaction txn)

Returns the length of the array using an existing transaction.

Specified by:

length in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

Returns:

The number of elements in the array

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

getString

public String getString(int index)

Gets a string value at the specified index.

Specified by:

getString in interface net.carcdr.ycrdt.YArray

Parameters:

index - The index (0-based)

Returns:

The string value, or null if index is out of bounds or value is not a string

Throws:

IllegalStateException - if the array has been closed

getString

public String getString(net.carcdr.ycrdt.YTransaction txn,
 int index)

Gets a string value at the specified index using an existing transaction.

Specified by:

getString in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The index (0-based)

Returns:

The string value, or null if index is out of bounds or value is not a string

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

getDouble

public double getDouble(int index)

Gets a double value at the specified index.

Specified by:

getDouble in interface net.carcdr.ycrdt.YArray

Parameters:

index - The index (0-based)

Returns:

The double value, or 0.0 if index is out of bounds or value is not a number

Throws:

IllegalStateException - if the array has been closed

getDouble

public double getDouble(net.carcdr.ycrdt.YTransaction txn,
 int index)

Gets a double value at the specified index using an existing transaction.

Specified by:

getDouble in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The index (0-based)

Returns:

The double value, or 0.0 if index is out of bounds or value is not a number

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

insertString

public void insertString(net.carcdr.ycrdt.YTransaction txn,
 int index,
 String value)

Inserts a string value at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     array.insertString(txn, 0, "First");
     array.insertString(txn, 1, "Second");
 }
 

Specified by:

insertString in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The position at which to insert (0-based)

value - The string value to insert

Throws:

IllegalArgumentException - if txn or value is null

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if index is negative or greater than the current length

insertString

public void insertString(int index,
 String value)

Inserts a string value at the specified index (creates implicit transaction).

Specified by:

insertString in interface net.carcdr.ycrdt.YArray

Parameters:

index - The position at which to insert (0-based)

value - The string value to insert

Throws:

IllegalArgumentException - if value is null

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if index is negative or greater than the current length

insertDouble

public void insertDouble(net.carcdr.ycrdt.YTransaction txn,
 int index,
 double value)

Inserts a double value at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     array.insertDouble(txn, 0, 1.0);
     array.insertDouble(txn, 1, 2.0);
 }
 

Specified by:

insertDouble in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The position at which to insert (0-based)

value - The double value to insert

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if index is negative or greater than the current length

insertDouble

public void insertDouble(int index,
 double value)

Inserts a double value at the specified index (creates implicit transaction).

Specified by:

insertDouble in interface net.carcdr.ycrdt.YArray

Parameters:

index - The position at which to insert (0-based)

value - The double value to insert

Throws:

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if index is negative or greater than the current length

pushString

public void pushString(net.carcdr.ycrdt.YTransaction txn,
 String value)

Appends a string value to the end of the array within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     array.pushString(txn, "First");
     array.pushString(txn, "Second");
 }
 

Specified by:

pushString in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

value - The string value to append

Throws:

IllegalArgumentException - if txn or value is null

IllegalStateException - if the array has been closed

pushString

public void pushString(String value)

Appends a string value to the end of the array (creates implicit transaction).

Specified by:

pushString in interface net.carcdr.ycrdt.YArray

Parameters:

value - The string value to append

Throws:

IllegalArgumentException - if value is null

IllegalStateException - if the array has been closed

pushDouble

public void pushDouble(net.carcdr.ycrdt.YTransaction txn,
 double value)

Appends a double value to the end of the array within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     array.pushDouble(txn, 1.0);
     array.pushDouble(txn, 2.0);
 }
 

Specified by:

pushDouble in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

value - The double value to append

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

pushDouble

public void pushDouble(double value)

Appends a double value to the end of the array (creates implicit transaction).

Specified by:

pushDouble in interface net.carcdr.ycrdt.YArray

Parameters:

value - The double value to append

Throws:

IllegalStateException - if the array has been closed

remove

public void remove(net.carcdr.ycrdt.YTransaction txn,
 int index,
 int length)

Removes a range of elements from the array within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     array.pushString(txn, "A");
     array.pushString(txn, "B");
     array.remove(txn, 0, 1); // Remove "A"
 }
 

Specified by:

remove in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The starting position (0-based)

length - The number of elements to remove

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if the range is invalid

remove

public void remove(int index,
 int length)

Removes a range of elements from the array (creates implicit transaction).

Specified by:

remove in interface net.carcdr.ycrdt.YArray

Parameters:

index - The starting position (0-based)

length - The number of elements to remove

Throws:

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if the range is invalid

insertDoc

public void insertDoc(net.carcdr.ycrdt.YTransaction txn,
 int index,
 net.carcdr.ycrdt.YDoc subdoc)

Inserts a YDoc subdocument at the specified index within an existing transaction.

This allows embedding one YDoc inside another, enabling hierarchical document structures and composition.

Example:

 try (YDoc parent = new JniYDoc();
      YDoc child = new JniYDoc();
      YArray array = parent.getArray("myarray");
      YTransaction txn = parent.beginTransaction()) {
     array.insertDoc(txn, 0, child);
 }
 

Specified by:

insertDoc in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The position at which to insert (0-based)

subdoc - The YDoc subdocument to insert

Throws:

IllegalArgumentException - if txn or subdoc is null

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if index is negative or greater than the current length

insertDoc

public void insertDoc(int index,
 net.carcdr.ycrdt.YDoc subdoc)

Inserts a YDoc subdocument at the specified index (creates implicit transaction).

This allows embedding one YDoc inside another, enabling hierarchical document structures and composition.

Example:

 try (YDoc parent = new JniYDoc();
      YDoc child = new JniYDoc();
      YArray array = parent.getArray("myarray")) {
     array.insertDoc(0, child);
 }
 

Specified by:

insertDoc in interface net.carcdr.ycrdt.YArray

Parameters:

index - The position at which to insert (0-based)

subdoc - The YDoc subdocument to insert

Throws:

IllegalArgumentException - if subdoc is null

IllegalStateException - if the array has been closed

IndexOutOfBoundsException - if index is negative or greater than the current length

pushDoc

public void pushDoc(net.carcdr.ycrdt.YTransaction txn,
 net.carcdr.ycrdt.YDoc subdoc)

Appends a YDoc subdocument to the end of the array within an existing transaction.

This allows embedding one YDoc inside another, enabling hierarchical document structures and composition.

Example:

 try (YDoc parent = new JniYDoc();
      YDoc child = new JniYDoc();
      YArray array = parent.getArray("myarray");
      YTransaction txn = parent.beginTransaction()) {
     array.pushDoc(txn, child);
 }
 

Specified by:

pushDoc in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

subdoc - The YDoc subdocument to append

Throws:

IllegalArgumentException - if txn or subdoc is null

IllegalStateException - if the array has been closed

pushDoc

public void pushDoc(net.carcdr.ycrdt.YDoc subdoc)

Appends a YDoc subdocument to the end of the array (creates implicit transaction).

This allows embedding one YDoc inside another, enabling hierarchical document structures and composition.

Example:

 try (YDoc parent = new JniYDoc();
      YDoc child = new JniYDoc();
      YArray array = parent.getArray("myarray")) {
     array.pushDoc(child);
 }
 

Specified by:

pushDoc in interface net.carcdr.ycrdt.YArray

Parameters:

subdoc - The YDoc subdocument to append

Throws:

IllegalArgumentException - if subdoc is null

IllegalStateException - if the array has been closed

getDoc

public JniYDoc getDoc(int index)

Gets a YDoc subdocument at the specified index.

The returned YDoc must be closed by the caller when no longer needed.

Example:

 try (YDoc parent = new JniYDoc();
      YArray array = parent.getArray("myarray")) {
     array.pushDoc(new JniYDoc());
     try (YDoc retrieved = array.getDoc(0)) {
         // Use the subdocument
     }
 }
 

Specified by:

getDoc in interface net.carcdr.ycrdt.YArray

Parameters:

index - The index (0-based)

Returns:

The YDoc subdocument, or null if index is out of bounds or value is not a Doc

Throws:

IllegalStateException - if the array has been closed

getDoc

public JniYDoc getDoc(net.carcdr.ycrdt.YTransaction txn,
 int index)

Gets a YDoc subdocument at the specified index using an existing transaction.

The returned YDoc must be closed by the caller when no longer needed.

Specified by:

getDoc in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

index - The index (0-based)

Returns:

The YDoc subdocument, or null if index is out of bounds or value is not a Doc

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

toJson

public String toJson()

Returns a JSON string representation of the array.

Specified by:

toJson in interface net.carcdr.ycrdt.YArray

Returns:

A JSON string representation

Throws:

IllegalStateException - if the array has been closed

toJson

public String toJson(net.carcdr.ycrdt.YTransaction txn)

Returns a JSON string representation of the array using an existing transaction.

Specified by:

toJson in interface net.carcdr.ycrdt.YArray

Parameters:

txn - The transaction to use for this operation

Returns:

A JSON string representation

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the array has been closed

observe

public net.carcdr.ycrdt.YSubscription observe(net.carcdr.ycrdt.YObserver observer)

Registers an observer to be notified when this array changes.

The observer will be called whenever elements are added, removed, or modified in this array. The observer receives a YEvent containing details about the changes.

Example:

 try (YDoc doc = new JniYDoc();
      YArray array = doc.getArray("myarray");
      YSubscription sub = array.observe(event -> {
          System.out.println("Array changed!");
          for (YChange change : event.getChanges()) {
              // Handle change
          }
      })) {
     array.pushString("Hello"); // Observer is called
 }
 

Specified by:

observe in interface net.carcdr.ycrdt.YArray

Parameters:

observer - The observer to register (must not be null)

Returns:

A subscription handle that can be used to unregister the observer

Throws:

IllegalArgumentException - if observer is null

IllegalStateException - if this array has been closed

unobserveById

public void unobserveById(long subscriptionId)

Unregisters an observer by its subscription ID.

This method is typically called automatically when a YSubscription is closed. Users should prefer using try-with-resources with YSubscription rather than calling this method directly.

Parameters:

subscriptionId - The ID of the subscription to remove

isClosed

public boolean isClosed()

Checks if this YArray has been closed.

Specified by:

isClosed in interface net.carcdr.ycrdt.YArray

Returns:

true if this YArray has been closed, false otherwise

close

public void close()

Closes this YArray and releases native resources.

After calling this method, any operations on this YArray will throw IllegalStateException.

This method is idempotent - calling it multiple times has no effect after the first call.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface net.carcdr.ycrdt.YArray