Package net.carcdr.ycrdt.jni

Class JniYXmlElement

java.lang.Object

net.carcdr.ycrdt.jni.JniYXmlElement

All Implemented Interfaces:

AutoCloseable, net.carcdr.ycrdt.YXmlElement, net.carcdr.ycrdt.YXmlNode

public class JniYXmlElement
extends Object
implements net.carcdr.ycrdt.YXmlElement

YXmlElement represents a collaborative XML element type in a Y-CRDT document.

YXmlElement provides collaborative operations for XML elements including tag names and attributes. Multiple users can modify the same element 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();
      YXmlElement element = doc.getXmlElement("div")) {
     element.setAttribute("class", "container");
     element.setAttribute("id", "main");
     System.out.println(element.getTag()); // div
     System.out.println(element.getAttribute("class")); // container
 }
 

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
int	childCount()	Gets the number of child nodes in this element.
int	childCount(net.carcdr.ycrdt.YTransaction txn)	Gets the number of child nodes in this element using an existing transaction.
void	close()	Closes this YXmlElement and releases native resources.
String	getAttribute(String name)	Gets an attribute value by name.
String	getAttribute(net.carcdr.ycrdt.YTransaction txn, String name)	Gets an attribute value by name using an existing transaction.
String[]	getAttributeNames()	Gets all attribute names.
String[]	getAttributeNames(net.carcdr.ycrdt.YTransaction txn)	Gets all attribute names using an existing transaction.
Object	getChild(int index)	Gets the child node at the specified index.
Object	getChild(net.carcdr.ycrdt.YTransaction txn, int index)	Gets the child node at the specified index using an existing transaction.
int	getIndexInParent()	Gets the index of this element within its parent's children.
int	getIndexInParent(net.carcdr.ycrdt.YTransaction txn)	Gets the index of this element within its parent's children using an existing transaction.
net.carcdr.ycrdt.YXmlNode.NodeType	getNodeType()
Object	getParent()	Gets the parent of this XML element.
Object	getParent(net.carcdr.ycrdt.YTransaction txn)	Gets the parent of this XML element using an existing transaction.
String	getTag()	Returns the tag name of this XML element.
String	getTag(net.carcdr.ycrdt.YTransaction txn)	Returns the tag name of this XML element using an existing transaction.
JniYXmlElement	insertElement(int index, String tag)	Inserts an XML element child at the specified index.
JniYXmlElement	insertElement(net.carcdr.ycrdt.YTransaction txn, int index, String tag)	Inserts an XML element child at the specified index within an existing transaction.
JniYXmlText	insertText(int index)	Inserts an XML text child at the specified index.
JniYXmlText	insertText(net.carcdr.ycrdt.YTransaction txn, int index)	Inserts an XML text child at the specified index within an existing transaction.
boolean	isClosed()	Checks if this YXmlElement has been closed.
net.carcdr.ycrdt.YSubscription	observe(net.carcdr.ycrdt.YObserver observer)	Registers an observer to be notified when this XML element changes.
void	removeAttribute(String name)	Removes an attribute.
void	removeAttribute(net.carcdr.ycrdt.YTransaction txn, String name)	Removes an attribute within an existing transaction.
void	removeChild(int index)	Removes the child node at the specified index.
void	removeChild(net.carcdr.ycrdt.YTransaction txn, int index)	Removes the child node at the specified index within an existing transaction.
void	setAttribute(String name, String value)	Sets an attribute value.
void	setAttribute(net.carcdr.ycrdt.YTransaction txn, String name, String value)	Sets an attribute value within an existing transaction.
String	toString()	Returns the XML string representation of this element.
String	toString(net.carcdr.ycrdt.YTransaction txn)	Returns the XML string representation of this element 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, 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

getTag

public String getTag()

Returns the tag name of this XML element.

Specified by:

getTag in interface net.carcdr.ycrdt.YXmlElement

Returns:

The tag name

Throws:

IllegalStateException - if the XML element has been closed

getTag

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

Returns the tag name of this XML element using an existing transaction.

Specified by:

getTag in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

Returns:

The tag name

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML element has been closed

getAttribute

public String getAttribute(String name)

Gets an attribute value by name.

Specified by:

getAttribute in interface net.carcdr.ycrdt.YXmlElement

Parameters:

name - The attribute name

Returns:

The attribute value, or null if not found

Throws:

IllegalArgumentException - if name is null

IllegalStateException - if the XML element has been closed

getAttribute

public String getAttribute(net.carcdr.ycrdt.YTransaction txn,
 String name)

Gets an attribute value by name using an existing transaction.

Specified by:

getAttribute in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

name - The attribute name

Returns:

The attribute value, or null if not found

Throws:

IllegalArgumentException - if txn or name is null

IllegalStateException - if the XML element has been closed

setAttribute

public void setAttribute(String name,
 String value)

Sets an attribute value.

Specified by:

setAttribute in interface net.carcdr.ycrdt.YXmlElement

Parameters:

name - The attribute name

value - The attribute value

Throws:

IllegalArgumentException - if name or value is null

IllegalStateException - if the XML element has been closed

setAttribute

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

Sets an attribute value within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     element.setAttribute(txn, "class", "container");
     element.setAttribute(txn, "id", "main");
 }
 

Specified by:

setAttribute in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

name - The attribute name

value - The attribute value

Throws:

IllegalArgumentException - if txn, name or value is null

IllegalStateException - if the XML element has been closed

removeAttribute

public void removeAttribute(String name)

Removes an attribute.

Specified by:

removeAttribute in interface net.carcdr.ycrdt.YXmlElement

Parameters:

name - The attribute name to remove

Throws:

IllegalArgumentException - if name is null

IllegalStateException - if the XML element has been closed

removeAttribute

public void removeAttribute(net.carcdr.ycrdt.YTransaction txn,
 String name)

Removes an attribute within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     element.removeAttribute(txn, "class");
     element.removeAttribute(txn, "id");
 }
 

Specified by:

removeAttribute in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

name - The attribute name to remove

Throws:

IllegalArgumentException - if txn or name is null

IllegalStateException - if the XML element has been closed

getAttributeNames

public String[] getAttributeNames()

Gets all attribute names.

Specified by:

getAttributeNames in interface net.carcdr.ycrdt.YXmlElement

Returns:

An array of all attribute names

Throws:

IllegalStateException - if the XML element has been closed

getAttributeNames

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

Gets all attribute names using an existing transaction.

Specified by:

getAttributeNames in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

Returns:

An array of all attribute names

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML element has been closed

toString

public String toString()

Returns the XML string representation of this element.

Specified by:

toString in interface net.carcdr.ycrdt.YXmlElement

Overrides:

toString in class Object

Returns:

The XML string representation

Throws:

IllegalStateException - if the XML element has been closed

toString

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

Returns the XML string representation of this element using an existing transaction.

Specified by:

toString in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

Returns:

The XML string representation

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML element has been closed

childCount

public int childCount()

Gets the number of child nodes in this element.

Specified by:

childCount in interface net.carcdr.ycrdt.YXmlElement

Returns:

The number of child nodes

Throws:

IllegalStateException - if the XML element has been closed

childCount

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

Gets the number of child nodes in this element using an existing transaction.

Specified by:

childCount in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

Returns:

The number of child nodes

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML element has been closed

insertElement

public JniYXmlElement insertElement(int index,
 String tag)

Inserts an XML element child at the specified index.

Specified by:

insertElement in interface net.carcdr.ycrdt.YXmlElement

Parameters:

index - The index at which to insert the child

tag - The tag name for the new element

Returns:

The new child element

Throws:

IllegalArgumentException - if tag is null

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

insertElement

public JniYXmlElement insertElement(net.carcdr.ycrdt.YTransaction txn,
 int index,
 String tag)

Inserts an XML element child at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     element.insertElement(txn, 0, "div");
     element.insertElement(txn, 1, "span");
 }
 

Specified by:

insertElement in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

index - The index at which to insert the child

tag - The tag name for the new element

Returns:

The new child element

Throws:

IllegalArgumentException - if txn or tag is null

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

insertText

public JniYXmlText insertText(int index)

Inserts an XML text child at the specified index.

Specified by:

insertText in interface net.carcdr.ycrdt.YXmlElement

Parameters:

index - The index at which to insert the child

Returns:

The new child text node

Throws:

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

insertText

public JniYXmlText insertText(net.carcdr.ycrdt.YTransaction txn,
 int index)

Inserts an XML text child at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     element.insertText(txn, 0);
     element.insertText(txn, 1);
 }
 

Specified by:

insertText in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

index - The index at which to insert the child

Returns:

The new child text node

Throws:

IllegalArgumentException - if txn is null

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

getChild

public Object getChild(int index)

Gets the child node at the specified index. The returned object can be either YXmlElement or YXmlText.

Specified by:

getChild in interface net.carcdr.ycrdt.YXmlElement

Parameters:

index - The index of the child to retrieve

Returns:

The child node, or null if not found

Throws:

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

getChild

public Object getChild(net.carcdr.ycrdt.YTransaction txn,
 int index)

Gets the child node at the specified index using an existing transaction. The returned object can be either YXmlElement or YXmlText.

Specified by:

getChild in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

index - The index of the child to retrieve

Returns:

The child node, or null if not found

Throws:

IllegalArgumentException - if txn is null

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

removeChild

public void removeChild(int index)

Removes the child node at the specified index.

Specified by:

removeChild in interface net.carcdr.ycrdt.YXmlElement

Parameters:

index - The index of the child to remove

Throws:

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

removeChild

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

Removes the child node at the specified index within an existing transaction.

Use this method to batch multiple operations:

 try (JniYTransaction txn = doc.beginTransaction()) {
     element.removeChild(txn, 0);
     element.removeChild(txn, 0);
 }
 

Specified by:

removeChild in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

index - The index of the child to remove

Throws:

IllegalArgumentException - if txn is null

IndexOutOfBoundsException - if index is negative

IllegalStateException - if the XML element has been closed

getParent

public Object getParent()

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

Specified by:

getParent in interface net.carcdr.ycrdt.YXmlElement

Returns:

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

Throws:

IllegalStateException - if the XML element has been closed

getParent

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

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

Specified by:

getParent in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

Returns:

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

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML element has been closed

getIndexInParent

public int getIndexInParent()

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

Specified by:

getIndexInParent in interface net.carcdr.ycrdt.YXmlElement

Returns:

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

Throws:

IllegalStateException - if the XML element has been closed

getIndexInParent

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

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

Specified by:

getIndexInParent in interface net.carcdr.ycrdt.YXmlElement

Parameters:

txn - Transaction handle

Returns:

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

Throws:

IllegalArgumentException - if txn is null

IllegalStateException - if the XML element has been closed

observe

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

Registers an observer to be notified when this XML element changes.

The observer will be called whenever children are added/removed or attributes are modified in this element. The observer receives a YEvent containing details about the changes.

Example:

 try (YDoc doc = new JniYDoc();
      YXmlElement element = doc.getXmlElement("div");
      YSubscription sub = element.observe(event -> {
          System.out.println("Element changed!");
          for (YChange change : event.getChanges()) {
              // Handle change
          }
      })) {
     element.setAttribute("class", "active"); // Observer is called
 }
 

Specified by:

observe in interface net.carcdr.ycrdt.YXmlElement

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 element 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 YXmlElement has been closed.

Specified by:

isClosed in interface net.carcdr.ycrdt.YXmlElement

Returns:

true if this YXmlElement has been closed, false otherwise

close

public void close()

Closes this YXmlElement and releases native resources.

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