Interface TreeSession

public interface TreeSession

Interface responsible for storing element trees. An element tree corresponds to a hierarchical data structure in a tree format in which the elements are arranged as nodes of that tree. This tree can be created freely or from a data structure whose objects, in that structure, behave like a tree but are arranged linearly. By invoking TreeTransaction.initializeSession(String, Collection), this linear structure is transformed into an actual tree structure.

The sessions are initialized by the TreeTransaction interface, which can manage one or more sessions, where each session represents a tree instance in the HappyTree API context. Although the TreeTransaction interface is able to manage instances of TreeSession, it can only do so one at a time. Thus, to handle a given session, it must be captured first by invoking TreeTransaction.sessionCheckout(String). On each session change via this method, the chosen session becomes the current session so the TreeTransaction interface can manipulate it.

It is important to note that when invoking TreeTransaction.initializeSession(String, Class) or TreeTransaction.initializeSession(String, Collection), the session is automatically made available to the TreeTransaction. Thus, the session is ready for manipulation immediately after initialization.

A session contains three fundamental states:

Session States

State	Exists?	Can it be handled?
Activated	✔	✔
Deactivated	✔	X
Destroyed	X	X

An active session, as noted above, exists and can be freely handled. A deactivated session, on the other hand, although it cannot be handled, still remains in memory, waiting only to be activated so it can be handled. In this case, the tree and its elements are 'alive' in memory but disabled.

A destroyed session is one that previously existed but has been permanently removed along with the entire tree and its elements. A destroyed session never returns to its natural state. It represents the end of its lifecycle.

Author:

Diego Madson de Andrade Nóbrega

See Also:

• TreeManager
• Element

Method Summary

Modifier and Type	Method	Description
String	getSessionId()	Returns the session identifier name.
boolean	isActive()	Verifies whether the session is active.
<T> Element<T>	tree()	Returns the entire tree session structure, represented by the root element.

Method Details

getSessionId

String getSessionId()

Returns the session identifier name.

A session identifier is defined when the session is initialized by invoking the TreeTransaction.initializeSession(String, Class) or TreeTransaction.initializeSession(String, Collection). This identifier must be unique.

Returns:

the session identifier name

isActive

boolean isActive()

Verifies whether the session is active.

Here, the method considers just two session states:

• Activated
• Deactivated

The Destroyed state is not considered because it is a null state.

Returns:

true if the session is active, false otherwise

tree

<T> Element<T> tree()

Returns the entire tree session structure, represented by the root element.

This method works similarly to the TreeManager.root() method, returning the root element of the tree. From the root element, it is possible to navigate through all its children, each child's children, and so on recursively, thus accessing the entire tree structure.

Below is an example of a tree structure with its root element and children:

                        ELEMENT(ROOT)
                              /\
                    ELEMENT(A)  ELEMENT(B)
                        /\         /\
                   E(A1) E(A2) E(B1) E(B2)

The root element is a special element that has no @Id, @Parent, or wrapped object node. It is created automatically by the core API when the session is initialized, that is, when invoking TreeTransaction.initializeSession(String, Class) or TreeTransaction.initializeSession(String, Collection) methods.

Only a few operations cannot be performed on the root element using the two interfaces: Element and TreeManager.

Element

Root Element Unsupported Operations

Method	Description
Element.getId()	Always returns null because the root element has no identifier.
Element.setId(Object)	No effect.
Element.getParent()	Always returns null because the root element has no @Parent.
Element.setParent(Object)	No effect.
Element.unwrap()	Always returns null because the root element has no wrapped object node.
Element.wrap(Object)	No effect.

TreeManager

Root Element Unsupported Operations - First Parameter

Method	Description
TreeManager.cut(Element, Element)	Throws TreeException.
TreeManager.cut(Object, Object)	No effect.
TreeManager.copy(Element, Element)	Throws TreeException.
TreeManager.removeElement(Element)	Throws TreeException.
TreeManager.removeElement(Object)	No effect.
TreeManager.persistElement(Element)	Not possible.

Returns:

the root of the tree

See Also:

• TreeManager.root()