Package net.carcdr.ycrdt.jni

Class JniYXmlText

java.lang.Object

net.carcdr.ycrdt.jni.JniYXmlText

All Implemented Interfaces:

AutoCloseable, net.carcdr.ycrdt.YXmlNode, net.carcdr.ycrdt.YXmlText

public class JniYXmlText
extends Object
implements net.carcdr.ycrdt.YXmlText

YXmlText represents a collaborative XML text type in a Y-CRDT document.

YXmlText provides collaborative text editing operations specifically designed for XML documents. It supports insert, push, delete, and rich text formatting operations with automatic conflict resolution.

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();
      YXmlText xmlText = doc.getXmlText("myxmltext")) {
     xmlText.push("Hello");
     xmlText.push(" World");
     System.out.println(xmlText.toString()); // Hello World
 }
 

See Also:

• YDoc

Nested Class Summary

Nested classes/interfaces inherited from interface net.carcdr.ycrdt.YXmlNode

net.carcdr.ycrdt.YXmlNode.NodeType

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this YXmlText and releases native resources.
void	delete(int index, int length)	Deletes a range of text.
void	delete(net.carcdr.ycrdt.YTransaction txn, int index, int length)	Deletes a range of text within an existing transaction.
void	format(int index, int length, Map<String,Object> attributes)	Formats a range of text with the specified attributes.
void	format(net.carcdr.ycrdt.YTransaction txn, int index, int length, Map<String,Object> attributes)	Formats a range of text with the specified attributes within an existing transaction.
List<net.carcdr.ycrdt.FormattingChunk>	getFormattingChunks()	Returns the formatted text as a list of chunks with their formatting attributes.
List<net.carcdr.ycrdt.FormattingChunk>	getFormattingChunks(net.carcdr.ycrdt.YTransaction txn)	Returns the formatted text as a list of chunks with their formatting attributes using an existing transaction.
int	getIndexInParent()	Gets the index of this text node within its parent's children.
int	getIndexInParent(net.carcdr.ycrdt.YTransaction txn)	Gets the index of this text node within its parent's children using an existing transaction.
net.carcdr.ycrdt.YXmlNode.NodeType	getNodeType()
Object	getParent()	Gets the parent of this XML text node.
Object	getParent(net.carcdr.ycrdt.YTransaction txn)	Gets the parent of this XML text node using an existing transaction.
void	insert(int index, String chunk)	Inserts text at the specified index.
void	insert(net.carcdr.ycrdt.YTransaction txn, int index, String chunk)	Inserts text at the specified index within an existing transaction.
void	insertWithAttributes(int index, String chunk, Map<String,Object> attributes)	Inserts text with formatting attributes at the specified index.
void	insertWithAttributes(net.carcdr.ycrdt.YTransaction txn, int index, String chunk, Map<String,Object> attributes)	Inserts text with formatting attributes at the specified index within an existing transaction.
boolean	isClosed()	Checks if this YXmlText has been closed.
int	length()	Returns the length of the text in characters.
int	length(net.carcdr.ycrdt.YTransaction txn)	Returns the length of the text in characters using an existing transaction.
net.carcdr.ycrdt.YSubscription	observe(net.carcdr.ycrdt.YObserver observer)	Registers an observer to be notified of changes to this XML text.
void	push(String chunk)	Appends text to the end of the XML text.
void	push(net.carcdr.ycrdt.YTransaction txn, String chunk)	Appends text to the end of the XML text within an existing transaction.
String	toString()	Returns the string representation of the XML text content.
String	toString(net.carcdr.ycrdt.YTransaction txn)	Returns the string representation of the XML text content using an existing transaction.
void	unobserveById(long subscriptionId)	Package-private method to unobserve by subscription ID.

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.carcdr.ycrdt.YXmlNode

asElement, asText

Method Details

getNodeType

public net.carcdr.ycrdt.YXmlNode.NodeType getNodeType()

Specified by:

getNodeType in interface net.carcdr.ycrdt.YXmlNode

length

public int length()

Returns the length of the text in characters.

Specified by:

length in interface net.carcdr.ycrdt.YXmlText

Returns:

The text length

Throws:

IllegalStateException - if the XML text has been closed

length

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

Returns the length of the text in characters using an existing transaction.

Specified by:

length in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - The transaction to use for this operation

Returns:

The text length

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML text has been closed

toString

public String toString()

Returns the string representation of the XML text content.

Specified by:

toString in interface net.carcdr.ycrdt.YXmlText

Overrides:

toString in class Object

Returns:

The text content as a string

Throws:

IllegalStateException - if the XML text has been closed

toString

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

Returns the string representation of the XML text content using an existing transaction.

Specified by:

toString in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - The transaction to use for this operation

Returns:

The text content as a string

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML text has been closed

insert

public void insert(net.carcdr.ycrdt.YTransaction txn,
 int index,
 String chunk)

Inserts text at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     xmlText.insert(txn, 0, "Hello");
     xmlText.insert(txn, 5, " World");
 }
 

Specified by:

insert in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - Transaction handle

index - The index at which to insert the text (0-based)

chunk - The text to insert

Throws:

IllegalArgumentException - if txn or chunk is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index is negative

insert

public void insert(int index,
 String chunk)

Inserts text at the specified index.

Specified by:

insert in interface net.carcdr.ycrdt.YXmlText

Parameters:

index - The index at which to insert the text (0-based)

chunk - The text to insert

Throws:

IllegalArgumentException - if chunk is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index is negative

push

public void push(net.carcdr.ycrdt.YTransaction txn,
 String chunk)

Appends text to the end of the XML text within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     xmlText.push(txn, "Hello");
     xmlText.push(txn, " World");
 }
 

Specified by:

push in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - Transaction handle

chunk - The text to append

Throws:

IllegalArgumentException - if txn or chunk is null

IllegalStateException - if the XML text has been closed

push

public void push(String chunk)

Appends text to the end of the XML text.

Specified by:

push in interface net.carcdr.ycrdt.YXmlText

Parameters:

chunk - The text to append

Throws:

IllegalArgumentException - if chunk is null

IllegalStateException - if the XML text has been closed

delete

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

Deletes a range of text within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     xmlText.delete(txn, 0, 5);
     xmlText.delete(txn, 0, 3);
 }
 

Specified by:

delete in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - Transaction handle

index - The starting index of the deletion (0-based)

length - The number of characters to delete

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index or length is negative

delete

public void delete(int index,
 int length)

Deletes a range of text.

Specified by:

delete in interface net.carcdr.ycrdt.YXmlText

Parameters:

index - The starting index of the deletion (0-based)

length - The number of characters to delete

Throws:

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index or length is negative

insertWithAttributes

public void insertWithAttributes(net.carcdr.ycrdt.YTransaction txn,
 int index,
 String chunk,
 Map<String,Object> attributes)

Inserts text with formatting attributes at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     Map<String, Object> bold = Map.of("b", true);
     xmlText.insertWithAttributes(txn, 0, "Hello", bold);
     xmlText.insertWithAttributes(txn, 5, " World", bold);
 }
 

Specified by:

insertWithAttributes in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - Transaction handle

index - The index at which to insert the text (0-based)

chunk - The text to insert

attributes - A map of formatting attributes to apply to the text

Throws:

IllegalArgumentException - if txn, chunk or attributes is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index is negative

insertWithAttributes

public void insertWithAttributes(int index,
 String chunk,
 Map<String,Object> attributes)

Inserts text with formatting attributes at the specified index.

The attributes map can contain formatting information such as:

• Bold: Map.of("b", true)
• Italic: Map.of("i", true)
• Font: Map.of("font", "Arial")
• Color: Map.of("color", "#FF0000")

Example usage:

 Map<String, Object> bold = Map.of("b", true);
 xmlText.insertWithAttributes(0, "Hello", bold);
 

Specified by:

insertWithAttributes in interface net.carcdr.ycrdt.YXmlText

Parameters:

index - The index at which to insert the text (0-based)

chunk - The text to insert

attributes - A map of formatting attributes to apply to the text

Throws:

IllegalArgumentException - if chunk or attributes is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index is negative

format

public void format(net.carcdr.ycrdt.YTransaction txn,
 int index,
 int length,
 Map<String,Object> attributes)

Formats a range of text with the specified attributes within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     Map<String, Object> bold = Map.of("b", true);
     xmlText.format(txn, 0, 5, bold);
     xmlText.format(txn, 6, 5, bold);
 }
 

Specified by:

format in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - Transaction handle

index - The starting index of the range to format (0-based)

length - The number of characters to format

attributes - A map of formatting attributes to apply

Throws:

IllegalArgumentException - if txn or attributes is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index or length is negative

format

public void format(int index,
 int length,
 Map<String,Object> attributes)

Formats a range of text with the specified attributes.

This method applies formatting to existing text. The attributes map can contain formatting information such as:

• Bold: Map.of("b", true)
• Italic: Map.of("i", true)
• Underline: Map.of("u", true)

To remove formatting, pass null as the attribute value:

 Map<String, Object> removeBold = Map.of("b", null);
 xmlText.format(0, 5, removeBold);
 

Example usage:

 xmlText.insert(0, "Hello World");
 Map<String, Object> bold = Map.of("b", true);
 xmlText.format(0, 5, bold); // Makes "Hello" bold
 

Specified by:

format in interface net.carcdr.ycrdt.YXmlText

Parameters:

index - The starting index of the range to format (0-based)

length - The number of characters to format

attributes - A map of formatting attributes to apply

Throws:

IllegalArgumentException - if attributes is null

IllegalStateException - if the XML text has been closed

IndexOutOfBoundsException - if index or length is negative

getParent

public Object getParent()

Gets the parent of this XML text node. The parent can be either a YXmlElement or YXmlFragment.

Specified by:

getParent in interface net.carcdr.ycrdt.YXmlText

Returns:

The parent node (YXmlElement or YXmlFragment), or null if this text node has no parent

Throws:

IllegalStateException - if the XML text has been closed

getParent

public Object getParent(net.carcdr.ycrdt.YTransaction txn)

Gets the parent of this XML text node using an existing transaction. The parent can be either a YXmlElement or YXmlFragment.

Specified by:

getParent in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - The transaction to use for this operation

Returns:

The parent node (YXmlElement or YXmlFragment), or null if this text node has no parent

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML text has been closed

getIndexInParent

public int getIndexInParent()

Gets the index of this text node within its parent's children.

Specified by:

getIndexInParent in interface net.carcdr.ycrdt.YXmlText

Returns:

The 0-based index within parent, or -1 if this text node has no parent

Throws:

IllegalStateException - if the XML text has been closed

getIndexInParent

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

Gets the index of this text node within its parent's children using an existing transaction.

Specified by:

getIndexInParent in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - The transaction to use for this operation

Returns:

The 0-based index within parent, or -1 if this text node has no parent

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML text has been closed

getFormattingChunks

public List<net.carcdr.ycrdt.FormattingChunk> getFormattingChunks()

Returns the formatted text as a list of chunks with their formatting attributes.

This method retrieves the complete delta representation of the text, where each chunk contains text content and its associated formatting attributes. This is useful for converting Y-CRDT formatted text to other rich text formats like ProseMirror.

Example usage:

 try (YDoc doc = new JniYDoc();
      YXmlText text = doc.getXmlText("mytext")) {
     text.insertWithAttributes(0, "Hello", Map.of("bold", true));
     text.insert(5, " World");

     List<FormattingChunk> chunks = text.getFormattingChunks();
     for (FormattingChunk chunk : chunks) {
         System.out.println("Text: " + chunk.getText());
         if (chunk.hasAttributes()) {
             System.out.println("Attributes: " + chunk.getAttributes());
         }
     }
 }
 

Specified by:

getFormattingChunks in interface net.carcdr.ycrdt.YXmlText

Returns:

a list of formatting chunks representing the text and its formatting

Throws:

IllegalStateException - if the XML text has been closed

See Also:

• FormattingChunk

getFormattingChunks

public List<net.carcdr.ycrdt.FormattingChunk> getFormattingChunks(net.carcdr.ycrdt.YTransaction txn)

Returns the formatted text as a list of chunks with their formatting attributes using an existing transaction.

This method retrieves the complete delta representation of the text, where each chunk contains text content and its associated formatting attributes.

Specified by:

getFormattingChunks in interface net.carcdr.ycrdt.YXmlText

Parameters:

txn - The transaction to use for this operation

Returns:

a list of formatting chunks representing the text and its formatting

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML text has been closed

See Also:

• FormattingChunk

isClosed

public boolean isClosed()

Checks if this YXmlText has been closed.

Specified by:

isClosed in interface net.carcdr.ycrdt.YXmlText

Returns:

true if this YXmlText has been closed, false otherwise

observe

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

Registers an observer to be notified of changes to this XML text.

The observer will be called whenever this XML text is modified. Multiple observers can be registered on the same XML text.

Example:

 try (YSubscription sub = xmlText.observe(event -> {
     System.out.println("XML text changed!");
     for (YChange change : event.getChanges()) {
         System.out.println("  " + change);
     }
 })) {
     xmlText.insert(0, "Hello"); // Triggers observer
 }
 

Specified by:

observe in interface net.carcdr.ycrdt.YXmlText

Parameters:

observer - the observer to register

Returns:

a subscription handle that can be used to unobserve

Throws:

IllegalArgumentException - if observer is null

IllegalStateException - if this XML text has been closed

unobserveById

public void unobserveById(long subscriptionId)

Package-private method to unobserve by subscription ID. Called by YSubscription.close().

Parameters:

subscriptionId - the subscription ID to remove

close

public void close()

Closes this YXmlText and releases native resources.

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