PPO XML Definition

From TheSeed
Jump to: navigation, search

On this page you will find the definition of the XML used to generate a PPO object schema. To clarify the descriptions below note the following. The XML schema is the representation of an Object schema. The term attribute may be used in both contexts, but refers to different things.

Document

A document must start with the following tag:

<?xml version="1.0" encoding="UTF-8"?>

Note: All chosen names within an XML-definition may not be from a list of reserved words (across all supported database backends). A good starting point what to avoid is the list of MySQL reserved words.

XML Tags

project

Each project is encapsulated within a single database. Multiple projects may be hosted on one database-server. Projects that are to interact with each other must be hosted on the same database-server. The project tag surrounds the description of all objects within this project. The name of the project is reflected in the label attribute of the project tag. This will also be the name of the directory the generated perl-modules will reside. Projects may contain object elements.

<project label="MyProjectName">
...
</project>

object

Objects must reside inside of projects. They represent the types of data-objects which can be stored, retrieved and manipulated using the PPO. The object tag must be closed. The object must be named using the label attribute. This is the name the object can be accessed through. Objects may contain elements, representing their object-attributes and indices.

<object label="MyObjectName">
...
</object>

scalar

The scalar element represents an attribute of an object and may only appear within an object element. The label attribute of this element will be the name of the object attribute. The type attribute can be any of the following data types (the exact size and implementation of each data type depends on the backend):

  • BOOLEAN: true or false
  • INTEGER: signed integer value
  • FLOAT: signed floating-point number
  • TIMESTAMP: timestamp as number of seconds since the epoch
  • CHAR(n): field of n characters
  • TEXT: text field (eg. 64kb)
  • TEXT LONG: large text field (eg. 4GB)
  • BLOB: data blob, stored as input
  • BLOB LONG: large data blob
<scalar label="myAttributeName" type="INTEGER" />

object_ref

The object_ref element represents a reference to an object which is an attribute of the surrounding object. The label attribute of this element will be the name of the object attribute. The type attribute can be any object name; it may refer to objects within the same project or to object in other projects. If the referenced object is not stored in the same database, the type attribute must be preceeded by 'MyProjectName::' .

<object_ref label="myObjectAttributeName" type="ObjectTypeWithinThisProject" />

or

<object_ref label="myObjectAttributeName" type="MyProjectName::ObjectTypeWithinOtherProject" />

array

The array element represents an attribute of the surrounding object which is an array. Arrays must consist exactly one instance of either a scalar or an object_ref.

<array>
   <scalar label="myObjectAttributeName" type="INTEGER" />
</array>

or

<array>
   <object_ref label="myObjectAttributeName" type="MyObjectType" />
</array>

index

The index element defines a mySQL index for this object for faster accession. Any combination of the scalar attributes of an object may be indexed, however, you may not index on arrays or object references. Each attribute to be part of the index must be listed via an attribute element. The attribute elements label attribute must be the name of the object attribute to be part of the index. You may create any number of indices.

<index>
   <attribute label="myObjectAttributeNameA">
   <attribute label="myObjectAttributeNameB">
   ...
</index>

unique_index

The unique_index element defines a set of attributes for an object which in combination must be unique. Any combination of the scalar attributes of an object may be indexed, however, you may not index on arrays or object references. Each attribute to be part of the index must be listed via an attribute element. The attribute elements label attribute must be the name of the object attribute to be part of the index. You may create any number of indices.

<unique_index>
   <attribute label="myObjectAttributeNameA">
   <attribute label="myObjectAttributeNameB">
   ...
</unique_index>

Creating a unique index will cause an init method to be created for this combination of attributes, allowing you access to instances of this object.

my $object = $dbmaster->myObject->init( { attribute1 => 'value1',
                                          attribute2 => 'value2' } );