Unit State
In WebRatio, the state of a unit is represented by the Unit State Object, a particular data structure that represents the internal state of the particular unit (each type of unit has it's particular Unit State Object). In it's implementation, a Unit State Object is a Java Bean, containing all the data necessary to realize the particular task of the unit.
For the Content Units, the Unit State Object is used in the template definition to extract the information contained in it and to show them in the page where the unit is placed. The Java Bean of each unit contained in a page is stored in the JSP PageContext of the page.
Entity State Object
Every Unit State Object of Content Units contains at least two properties:
- int dataSize: which represents the number of elements to be displayed (the size of the "data" property)
- data: it's the Entity State Object, a data structure (Object or Object[]) that depends on the entity the unit is based on. This property contains all the data to be displayed (retrieved from the data source). For example, the entity "product" of Acme application is associated with a state object having the following properties:
- Integer OID: the value of the oid attribute
- Integer code: the value of the code attribute
- String description: the value of the description attribute
- String name: the value of the name attribute
- Double price: the value of the price attribute
- Object thumbnail: the value of the thumbnail attribute
- Boolean highlighted: the value of the highlighted attribute
Accessing Unit State Objects
As shown in the previous sections, the Unit State Objects contains all the information for the representation of the data extracted by the unit. The template of each unit must access to the Unit State Object and use the information contained in it to define the layout of the unit. In the template definition, JSTL (JavaServer Pages Standard Tag Library) is used to access to the Unit State Object. The JSTL encapsulates as simple tags the core functionality common to many Web applications. JSTL has support for common, structural tasks such as iteration and conditionals, tags for manipulating XML documents, internationalization tags, and SQL tags.
Using the <wr:UnitId/> tag it's possible to access to all the properties of a Unit State Object with the dot notation.
In the following sections, some Unit State Objects whith code examples are shown.
Data Unit State Object
The Data Unit is a Content unit that displays a set of attributes, which provides a meaningful view of a single instance of a given entity of the Data Model.
The Unit State Object for the Data Unit consists of the following properties:
- int dataSize: the number of entity state objects (zero or one).
- Object data: the entity state object.
The "dataSize" property is used in order to determine if an entity instance that meets all the conditions defined in the Unit exist (if there's something to be displayed). The "data" property contains the data to be displayed. The image shows the Entity State Object of a Data Unit based on the "product" entity of the ACME application:
As an example, it's possible to determine if the Unit State Object of a Data Unit contains some data to display, using the <c:if> tag:
<c:if test="${not(empty <wr:UnitId/>) and (<wr:UnitId/>.dataSize gt 0)}"> </c:if>
Here, the first condition "not(empty <wr:UnitId/>)" checks that the Unit State Object exists and the second condition "<wr:UnitId/>.dataSize gt 0" accesses the Unit State Object's "dataSize" property and checks that is greater than 0 (there are data to be displayed)
Using the <c:choose> tag, it's possible to explicitly manage the case in which the unit contains no data:
<c:choose>
<c:when test="${not(empty <wr:UnitId/>) and (<wr:UnitId/>.dataSize gt 0)}">
</c:when>
<c:otherwise>
</c:otherwise>
</c:choose>
Index Unit State Object
The Index Unit is a Content unit that presents multiple instances of an entity as an array and permits the user to select an object from such array.
The Unit State Object for the Index Unit consists of the following properties:
- int dataSize: the number of entity state objects
- Object[] data: the array of entity state objects
- int currentIndex: the zero-based index of the current entity state object
The "dataSize" property is used to represent the size of the array. The "data" property contains all the data to be displayed. The "currentIndex" is the index of the array element that the user has select as the current one.
It's worth noting the difference between the "data" property of the Data Unit and the "data" property of the Index Unit: in the Data Unit, the "data" property is an Object (every attribute contains a single instance) since the Data Unit provides a view of a single instance of an entity, while the "data" property in the Index Unit State Object is an array, since the Index Unit provides a view of multiple instances. The image shows the Entity State Object of a Index Unit based on the "product" entity of the ACME application:
In the Index Unit the data property is an array. It's possible to iterate over it using the <c:forEach> tag:
<c:forEach var="current" varStatus="status" items="${<wr:UnitId/>.data}">
<c:set var="index" value="${status.index}"/>
</c:forEach>
Where:
- items is the collection of items to iterate over, in this case the Index Unit State Object's "data" property.
- varStatus is the exported scoped variable for the status of the iteration. Object exported is of type javax.servlet.jsp.jstl.core.LoopTagStatus.
- var is the exported scoped variable for the current item of the iteration. Its type depends on the object of the underlying collection.
The <c:set> JSTL tag creates a variable named "index" containing the index of the current iteration (using the "status" variable).
Hierarchical Index Unit State Object
The Hierarchical Index Unit is a Content unit that presents the instances of multiple entities connected by relationships as a hierarchy and permits the user to select one object from such hierarchy.
The Unit State Object for the Hierarchical Index Unit consists of the following properties:
- int dataSize: the number of entity state objects
- Object[] data: the array of entity state objects
- int {levelId}dataSize: the number of entity state objects of the level
- Object[] {levelId}data: the array of entity state objects of the level
The state object at the root level depends on the entity the unit is based on, and on the child levels. For example, if the unit is based on the "category" entity of the ACME application and contains an immediate child level (identified by hiulvl1), the state object at the root level includes the following properties:
- Integer OID: the value of the oid attribute
- String category: the value of the Category attribute
- int hiulvl1dataSize: the number of entity state objects of the child level
- Object[] hiulvl1data: the array of entity state objects of the level of the child level
The state object at the n-th level has a structure similar to the structure of the state object at the root level. It depends on the entity the n-th level is based on, and on the nested child levels. For example, if the unit is based on the ACME "product" entity and contains an immediate child level (identified by hiulvl2), the state object includes the following properties:
- Integer OID: the value of the oid attribute
- String category: the value of the Category attribute
- Integer code: the value of the code attribute
- String description: the value of the description attribute
- String name: the value of the name attribute
- Double price: the value of the price attribute
- Object thumbnail: the value of the thumbnail attribute
- Boolean highlighted: the value of the highlighted attribute
- int hiulvl2dataSize: the number of entity state objects of the child level
- Object[] hiulvl2data: the array of entity state objects of the level of the child level
The structure presented above is valid only for multi-branch hierarchical index units, i.e. for hierarchical units presenting at least one level with two or more immediate child levels. In general, every level contains the reference to his child levels, as in a tree structure. The image shows the Entity State Object of a Hierarchical Unit based on the "product" entity with a level based on the "combination" entity of the ACME application:
Let's see how to iterate over the "data" property of the first level and the second level related to the current element of the first level of a Hierarchical Index Unit, according to the Unit State Object:
<c:forEach var="level1current" varStatus="level1status" items="${<wr:UnitId/>.data}">
<c:set var="level1" value="${level1status.index}" />
<c:forEach items="${level1current.hiulvl1data}" var="level2current" varStatus="level2status">
<c:set var="level2" value="${level2status.index}" />
</c:forEach>
</c:forEach>
In order to iterate over the second level data, related to the "level1" current element of the Hierarchical Unit, a nested iteration is needed.