Data Objects #
This page contains the following content:
Data Objects, Case Bases, and Object Pools #
Creating Instances of Data Classes (Data Objects) #
Instances of instantiable data classes (see data classes) can be created during run-time using a loaded model (default model can be retrieved
ModelFactory.getDefaultModel()). It has a method
createObject which requires the name of the desired data class. After the creation of the object/instance, class-specific values can be set by using the corresponding methods:
StringObject stringObjectA = ModelFactory.getDefaultModel().createObject(StringClass.CLASS_NAME); stringObjectA.setNativeString("test");
For system data classes, the model has methods to return the data class directly. Thus, the String class used above can also be queried with the
StringObject stringObjectB = model.getStringSystemClass().newObject();
For system and custom user data classes, the model provides the following method to access a class by its name:
StringObject stringObjectC = model.getClass(StringClass.CLASS_NAME).newObject();
Properties of Data Objects #
In addition to the “main value” of a data object, each data object can store properties to store additional information about the object. For example, maintenance information like how often the object was retrieved is stored in such a way. The system knows several predefined properties but user-defined ones are also possible. A property is a key-value pair whereby the key as well as the value must be a string. This restriction is necessary to be able to embed the properties into XML. If another data type has to be handled an encoding to and from string must be realised.
Object Pools #
In ProCAKE, data objects can be collected in pools. These pools exist in two variants, as readable object pools and as
writeable object pools. A pool can contain arbitrary
DataObjects. That means that the objects can belong to
Each object pool must have an identifier and this identifier must be unique in complete ProCAKE during run-time. If the
pool is created using the method
ObjectPoolFactory.newObjectPool(), this is guaranteed. If custom object pools are
created, it must be taken care, that the identifier is different to
To access a data object in an object pool, each data object has to be identified. A data object can be element of several pools, so a simple identification number is not sufficient, because it must be unique in all pools. Therefore, a data object has a specific objectId. This id can be set manually, for example in the casebase. In this case, the user is responsible for ensuring that this id is unique. If an object without an id is read into an object pool, an id is generated. This id consists of two parts: the base and the offset. The base is a namespace and depends on the location, where the object is stored. Mainly this is an object pool. The offset is an unique id that must be unique within the object pool and is managed by the object pool itself. This is just a necessary pre-condition to realize the synchronization and identification of objects, not the complete synchronization technique.
New objectIds can be created manually using the
ObjectPoolFactory.newObjectId(String objectPoolId, String offset) or are created automatically using the
WriteableObjectPool.store(DataObject dataObject). To access the objects of a pool without using the id,
DataObjectIterator can be used. It extends the standard Iterator and contains one additional
nextDataObject, that returns a DataObject.
Readable Object Pools #
ReadableObjectPool pool is a container for data objects. The pool provides special access methods that are
interpreting the ObjectIds of the data objects. This class is only an interface, so it’s not possible, to create any
instances of it.
To check, if two object pools have the same objects in, the method
hasSameValueAsIn(ReadableObjectPool objectPool) can
be used. If two pools contain the same objects,
true is returned.
Writeable Object Pools #
WritableObjectPool extends the
ReadableObjectPool and contains additional methods to modify the pool.
store methods are provided.
remove method needs any kind of data object or the offset of the object, to remove this data object from the
pool. The objectId is automatically removed from the object. It is also possible to use the method
clear the complete pool.
store method needs any kind of data object, which will be stored in the pool. Thereby, a new unique
objectId is automatically created, if the object does not have one already. If the object is already a member of the pool, nothing will happen. It’s also possible to use the method
storeAll with a collection or a ReadableObjectPool, which will be stored in the WritableObjectPool.
When using the method
CAKEInstance.start, a WritableObjectPool is returned. If the method had a case base given, the objects of the case base are all stored in the pool.
Using a CSV Case Base #
It’s also possible, to use a CSV file as case base or parse it into an existing one. In a CSV file, only structural
cases can be represented. So, the parser can be used to create aggregate objects. To read and use
such a file, the class
CakeCSVParser can be used. It requires the path of the CSV file, which can be set by using
setFilename. This looks like:
CakeCSVParser csvParser = new CakeCSVParser(); csvParser.setFilename("casebase.csv");
For using the parser, a declaration containing the corresponding classes is necessary. It’s important, that every name in the CSV file is unique, otherwise an exception will be thrown. If the column names in the CSV are equal to the attribute names of the aggregate class to map each CSV example to, the CSV parser can be used without any more configurations.
For example, a simple CSV file can look like that:
"attribute1","attribute2" "value1","valueA" "value2","valueB"
In the above example, it is necessary, that the model contains an aggregate class that contains attributes with the names attribute1 and attribute2. Otherwise, the file cannot be read without further information.
If there are different names in the CSV columns and the model class or the file doesn’t contain any header information at all, a mapping file is required. This file also has to be in the CSV format. It contains the name of the column in the CSV file as the first column and the name in the model as the second column. It might look like this:
"nameInCSV","nameInModell" "attribute1","attributeA" "attribute2","attributeB"
Here, attribute1 will correspond to attributeA in the model, as well as attribute2 will be mapped to attributeB.
Alternatively, the column number can be the first argument and the attribute name in the model the second one. This can look like:
"rowInCSV","nameInModell" 1,"attributeA" 2,"attributeB"
Here, the values of the first column of the CSV file containing the examples will correspond to attributeA in the model, and the values of the second column to attributeB.
To use such a mapping file, the method
setMappingFile can be used. This might look like this:
When the configuration of the parser is finished, it can be started via the
createAggregateObjects(String className). The parameter className must be the name of the corresponding
aggregate class in the model. The method will return a list of aggregate objects, filled with the values of the CSV
file as aggregate attributes.
Because the creation of the objects runs in parallel, the order of the objects in the object pool isn’t deterministic.
It’s also possible to use aggregate classes, which contain nested aggregate classes in any depth. In this case, the classes need to be defined in the model file. The attribute names need to be unique, so they or their mapping partners can be found in the CSV file. This way, the information of the CSV file, which contains no hierarchical relations, can be mapped to an aggregate object that might contain nested attributes, thus expressing hierarchical relationships.
Cloning and Comparing Objects #
ProCAKE provides particular methods for cloning data objects, i.e.
DataObject copy(), and comparing them, i.e.
boolean hasSameValueAsIn(DataObject object), in the class
copy() makes a deep copy of the data object. This means that the method is called recursively for any nested data object, e.g., list elements or aggregate attributes.
The following code gives an example, where a String object is created and copied:
StringObject stringObject = (StringObject) ModelFactory.getDefaultModel().createObject(StringClass.CLASS_NAME); stringObject.setNativeString("test"); StringObject copiedStringObject = (StringObject) stringObject.copy();
copiedStringObject is an instance of the same class (
StringObject) and contains the same value as the original object (
In order to compare if the values of two objects are equal, the method
hasSameValueAsIn can be used.
It performs no reference check but instead checks all relevant information of two data objects for equality.
The definition of relevant information is different for each data object.
For instance, two integer objects are simply equal if their values are equal.
In contrast, the test for equality of two lists (or even NEST graphs) is much more complex.
hasSameValueAsIn() makes recursive calls for nested data objects, analogous to
The following code gives an example, using the objects from the example of the
copy method above:
copiedStringObject.hasSameValueAsIn(stringObject); // returns true
This method call would return
true, because both objects contain the same value.
Using a String object, that contains another value, the method would return
When using the
hasSameValueAsIn method for objects, that instantiate different data classes, it returns
The following list contains a few more specific behaviors of some data classes:
- When comparing Numeric objects, it is checked, if the values are identical.
So, for example a Integer object with the value
1and a Double object with the value
1.0are identified as equal by this method.
- When comparing Numeric objects with String objects, it is checked, if the String object contains numeric values.
So, for example a Integer object with the value
1and a String object with the value
"1"are identified as equal by this method.
- When comparing Collection objects, it is checked, if they contain the same elements. Each element must appear at the same position in both collections (if the data structure supports positional information). So, for example a List object and a Set object, that both contain the same five values, are identified as equal by this method. Since it is possible that a List object contains an object more than once, this would lead to the method identifying both objects as unequal.
Object IDs #
Each data object in ProCAKE, can have an objectId. This id is necessary to identify an object in an object pool. For this purpose, the id must be unique.
The id can be set manually in the case base or afterwards by using the method
setId(String objectId). In this case, the user is responsible for ensuring that this id is unique. Otherwise, an exception would be thrown, when this object is read to an object pool.
For example, an id can be set in a casebase as follows:
<cdol:V id="exampleId" c="Void"/>
This represents a Void object, which can be identified by the id exampleId. It’s important to ensure, that no other object has this id.
During runtime, the id can be set as follows:
Note, that this requires an object voidObject, that has to be created before.
If an object without an id is read into an object pool, an id is generated. This id consists of two parts: the base and the offset. The base is a namespace and depends on the location, where the object is stored. Mainly this is an object pool. The offset is a unique id that must be unique within the object pool and is managed by the object pool itself. This type of new objectIds can be created manually using the method
ObjectPoolFactory.newObjectId(String objectPoolId, String offset). This method is also called automatically by the method
WriteableObjectPool.store(DataObject dataObject), if no id is set.
Readers and Writers #
This page contains a short overview of the (de-)serialization utilities provided within the ProCAKE framework which offer object IO capabilities for external projects.
ProCAKE provides several implementations for reading and writing objects. All the available reader and writer implementation are registered in the ‘composition.xml’ configuration file. See Configuration page for more details.
Reading Objects #
For instance, to read an object pool, the following method can be used:
WriteableObjectPool pool = IOUtil.readFile(filePath, WriteableObjectPool.class);
For reading an object with a specific reader, the name of the desired reader can be given as an argument as follows:
WriteableObjectPool pool = IOUtil.readFile(filePath, ObjectPoolParser.PARSERNAME);
To read a single data object, the ‘ObjectParser’ can be used:
DataObject object = IOUtil.readFile(filePath, ObjectParser.PARSERNAME);
The ‘StringReader’ can be used for reading arbitrary text files:
String stringObject = IOUtil.readFile(filePath, StringReader.READERNAME);
Writing Objects #
To write an object pool to a file, the following method can be used:
WriteableObjectPool poolToWrite = ObjectPoolFactory.newObjectPool(); IOUtil.writeFile(poolToWrite, filePath);
When writing an object, also a specific writer can be used. The name of the desired writer has to be given for this purpose:
IOUtil.writeFile(poolToWrite, filePath, ObjectPoolWriterImpl.WRITERNAME);
To write a data object as XML, the ‘ObjectPoolWriterImpl’ can be used:
IOUtil.writeFile(dataObject, filePath, ObjectWriterImpl.WRITERNAME);
To write a data object or Strings to a TXT file, the ‘StringWriter’ can be used:
IOUtil.writeFile(dataObject, filePath, StringWriter.WRITERNAME);
ProCAKE provides a utility class for using XStream, which supports both XML and JSON serialization. The utility class
XStreamUtil is located in the package
de.uni_trier.wi2.procake.utils.io.xstream and contains the respective methods
To serialize a
RetrievalResultList object to XML for instance, simply call
RetrievalResultList rrl; String serializedList = XStreamUtil.toXML(rrl);
To deserialize a
Query in XML representation to a
Query object, call
String queryObjectXML; QueryImpl query = XStreamUtil.fromXML(queryObjectXML);