Package net.carcdr.ycrdt.jni

Class JniYMap

java.lang.Object

net.carcdr.ycrdt.jni.JniYMap

All Implemented Interfaces:

AutoCloseable, net.carcdr.ycrdt.YMap

public class JniYMap
extends Object
implements net.carcdr.ycrdt.YMap

YMap represents a collaborative map type in a Y-CRDT document.

YMap provides efficient collaborative map operations with automatic conflict resolution. Multiple users can modify the same map 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();
      YMap map = doc.getMap("mymap")) {
     map.setString("name", "Alice");
     map.setDouble("age", 30.0);
     System.out.println(map.toJson()); // {"name":"Alice","age":30.0}
 }
 

See Also:

• YDoc

Method Summary

Modifier and Type	Method	Description
void	clear()	Removes all entries from the map.
void	clear(net.carcdr.ycrdt.YTransaction txn)	Removes all entries from the map within an existing transaction.
void	close()	Closes this YMap and releases native resources.
boolean	containsKey(String key)	Checks if a key exists in the map.
boolean	containsKey(net.carcdr.ycrdt.YTransaction txn, String key)	Checks if a key exists in the map using an existing transaction.
JniYDoc	getDoc(String key)	Gets a YDoc subdocument from the map by key.
JniYDoc	getDoc(net.carcdr.ycrdt.YTransaction txn, String key)	Gets a YDoc subdocument from the map by key using an existing transaction.
double	getDouble(String key)	Gets a double value by key.
double	getDouble(net.carcdr.ycrdt.YTransaction txn, String key)	Gets a double value by key using an existing transaction.
String	getString(String key)	Gets a string value by key.
String	getString(net.carcdr.ycrdt.YTransaction txn, String key)	Gets a string value by key using an existing transaction.
boolean	isClosed()	Checks if this YMap has been closed.
boolean	isEmpty()	Checks if the map is empty.
String[]	keys()	Gets all keys from the map.
String[]	keys(net.carcdr.ycrdt.YTransaction txn)	Gets all keys from the map using an existing transaction.
net.carcdr.ycrdt.YSubscription	observe(net.carcdr.ycrdt.YObserver observer)	Registers an observer to be notified when this map changes.
void	remove(String key)	Removes a key from the map.
void	remove(net.carcdr.ycrdt.YTransaction txn, String key)	Removes a key from the map within an existing transaction.
void	setDoc(String key, net.carcdr.ycrdt.YDoc subdoc)	Sets a YDoc subdocument value in the map.
void	setDoc(net.carcdr.ycrdt.YTransaction txn, String key, net.carcdr.ycrdt.YDoc subdoc)	Sets a YDoc subdocument value in the map within an existing transaction.
void	setDouble(String key, double value)	Sets a double value in the map.
void	setDouble(net.carcdr.ycrdt.YTransaction txn, String key, double value)	Sets a double value in the map within an existing transaction.
void	setString(String key, String value)	Sets a string value in the map.
void	setString(net.carcdr.ycrdt.YTransaction txn, String key, String value)	Sets a string value in the map within an existing transaction.
int	size()	Returns the number of entries in the map.
int	size(net.carcdr.ycrdt.YTransaction txn)	Returns the number of entries in the map using an existing transaction.
String	toJson()	Returns a JSON string representation of the map.
String	toJson(net.carcdr.ycrdt.YTransaction txn)	Returns a JSON string representation of the map 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

size

public int size()

Returns the number of entries in the map.

Specified by:

size in interface net.carcdr.ycrdt.YMap

Returns:

The size of the map

Throws:

IllegalStateException - if the map has been closed

size

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

Returns the number of entries in the map using an existing transaction.

Specified by:

size in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use for this operation

Returns:

The size of the map

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the map has been closed

isEmpty

public boolean isEmpty()

Checks if the map is empty.

Specified by:

isEmpty in interface net.carcdr.ycrdt.YMap

Returns:

true if the map contains no entries, false otherwise

Throws:

IllegalStateException - if the map has been closed

getString

public String getString(String key)

Gets a string value by key.

Specified by:

getString in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to look up

Returns:

The string value, or null if key not found or value is not a string

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if the map has been closed

getString

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

Gets a string value by key using an existing transaction.

Specified by:

getString in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use for this operation

key - The key to look up

Returns:

The string value, or null if key not found or value is not a string

Throws:

IllegalArgumentException - if txn or key is null

IllegalStateException - if the map has been closed

getDouble

public double getDouble(String key)

Gets a double value by key.

Specified by:

getDouble in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to look up

Returns:

The double value, or 0.0 if key not found or value is not a number

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if the map has been closed

getDouble

public double getDouble(net.carcdr.ycrdt.YTransaction txn,
 String key)

Gets a double value by key using an existing transaction.

Specified by:

getDouble in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use for this operation

key - The key to look up

Returns:

The double value, or 0.0 if key not found or value is not a number

Throws:

IllegalArgumentException - if txn or key is null

IllegalStateException - if the map has been closed

setString

public void setString(String key,
 String value)

Sets a string value in the map.

Specified by:

setString in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to set

value - The string value to set

Throws:

IllegalArgumentException - if key or value is null

IllegalStateException - if the map has been closed

setString

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

Sets a string value in the map within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     map.setString(txn, "name", "Alice");
     map.setString(txn, "city", "NYC");
 }
 

Specified by:

setString in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use

key - The key to set

value - The string value to set

Throws:

IllegalArgumentException - if txn, key, or value is null

IllegalStateException - if the map or transaction has been closed

setDouble

public void setDouble(String key,
 double value)

Sets a double value in the map.

Specified by:

setDouble in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to set

value - The double value to set

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if the map has been closed

setDouble

public void setDouble(net.carcdr.ycrdt.YTransaction txn,
 String key,
 double value)

Sets a double value in the map within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     map.setDouble(txn, "age", 30.0);
     map.setDouble(txn, "height", 165.5);
 }
 

Specified by:

setDouble in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use

key - The key to set

value - The double value to set

Throws:

IllegalArgumentException - if txn or key is null

IllegalStateException - if the map or transaction has been closed

remove

public void remove(String key)

Removes a key from the map.

Specified by:

remove in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to remove

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if the map has been closed

remove

public void remove(net.carcdr.ycrdt.YTransaction txn,
 String key)

Removes a key from the map within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     map.remove(txn, "key1");
     map.remove(txn, "key2");
 }
 

Specified by:

remove in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use

key - The key to remove

Throws:

IllegalArgumentException - if txn or key is null

IllegalStateException - if the map or transaction has been closed

containsKey

public boolean containsKey(String key)

Checks if a key exists in the map.

Specified by:

containsKey in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to check

Returns:

true if the key exists, false otherwise

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if the map has been closed

containsKey

public boolean containsKey(net.carcdr.ycrdt.YTransaction txn,
 String key)

Checks if a key exists in the map using an existing transaction.

Specified by:

containsKey in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use for this operation

key - The key to check

Returns:

true if the key exists, false otherwise

Throws:

IllegalArgumentException - if txn or key is null

IllegalStateException - if the map has been closed

keys

public String[] keys()

Gets all keys from the map.

Specified by:

keys in interface net.carcdr.ycrdt.YMap

Returns:

An array of all keys in the map

Throws:

IllegalStateException - if the map has been closed

keys

public String[] keys(net.carcdr.ycrdt.YTransaction txn)

Gets all keys from the map using an existing transaction.

Specified by:

keys in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use for this operation

Returns:

An array of all keys in the map

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the map has been closed

clear

public void clear()

Removes all entries from the map.

Specified by:

clear in interface net.carcdr.ycrdt.YMap

Throws:

IllegalStateException - if the map has been closed

clear

public void clear(net.carcdr.ycrdt.YTransaction txn)

Removes all entries from the map within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     map.clear(txn);
     map.setString(txn, "reset", "true");
 }
 

Specified by:

clear in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the map or transaction has been closed

setDoc

public void setDoc(String key,
 net.carcdr.ycrdt.YDoc subdoc)

Sets a YDoc subdocument value in the map.

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

Example:

 try (YDoc parent = new JniYDoc();
      YDoc child = new JniYDoc();
      YMap map = parent.getMap("mymap")) {
     map.setDoc("nested", child);
 }
 

Specified by:

setDoc in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to set

subdoc - The YDoc subdocument to set

Throws:

IllegalArgumentException - if key or subdoc is null

IllegalStateException - if the map has been closed

setDoc

public void setDoc(net.carcdr.ycrdt.YTransaction txn,
 String key,
 net.carcdr.ycrdt.YDoc subdoc)

Sets a YDoc subdocument value in the map within an existing transaction.

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

Use this method to batch multiple operations:

 try (YDoc parent = new JniYDoc();
      YDoc child = new JniYDoc();
      YMap map = parent.getMap("mymap");
      YTransaction txn = parent.beginTransaction()) {
     map.setDoc(txn, "nested", child);
     map.setString(txn, "type", "subdocument");
 }
 

Specified by:

setDoc in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use

key - The key to set

subdoc - The YDoc subdocument to set

Throws:

IllegalArgumentException - if txn, key, or subdoc is null

IllegalStateException - if the map or transaction has been closed

getDoc

public JniYDoc getDoc(String key)

Gets a YDoc subdocument from the map by key.

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

Example:

 try (YDoc parent = new JniYDoc();
      YMap map = parent.getMap("mymap")) {
     map.setDoc("nested", new JniYDoc());
     try (YDoc retrieved = map.getDoc("nested")) {
         // Use the subdocument
     }
 }
 

Specified by:

getDoc in interface net.carcdr.ycrdt.YMap

Parameters:

key - The key to look up

Returns:

The YDoc subdocument, or null if key not found or value is not a Doc

Throws:

IllegalArgumentException - if key is null

IllegalStateException - if the map has been closed

getDoc

public JniYDoc getDoc(net.carcdr.ycrdt.YTransaction txn,
 String key)

Gets a YDoc subdocument from the map by key 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.YMap

Parameters:

txn - The transaction to use for this operation

key - The key to look up

Returns:

The YDoc subdocument, or null if key not found or value is not a Doc

Throws:

IllegalArgumentException - if txn or key is null

IllegalStateException - if the map has been closed

toJson

public String toJson()

Returns a JSON string representation of the map.

Specified by:

toJson in interface net.carcdr.ycrdt.YMap

Returns:

A JSON string representation

Throws:

IllegalStateException - if the map has been closed

toJson

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

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

Specified by:

toJson in interface net.carcdr.ycrdt.YMap

Parameters:

txn - The transaction to use for this operation

Returns:

A JSON string representation

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the map has been closed

observe

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

Registers an observer to be notified when this map changes.

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

Example:

 try (YDoc doc = new JniYDoc();
      YMap map = doc.getMap("mymap");
      YSubscription sub = map.observe(event -> {
          System.out.println("Map changed!");
          for (YChange change : event.getChanges()) {
              // Handle change
          }
      })) {
     map.setString("key", "value"); // Observer is called
 }
 

Specified by:

observe in interface net.carcdr.ycrdt.YMap

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 map 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 YMap has been closed.

Specified by:

isClosed in interface net.carcdr.ycrdt.YMap

Returns:

true if this YMap has been closed, false otherwise

close

public void close()

Closes this YMap and releases native resources.

After calling this method, any operations on this YMap 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.YMap