Metadata Entities - ARCAD-Software/AFS GitHub Wiki

Metadata Entities define the structure and relationships between data Resources provided by the Metadata project management services. They contain attributes and associations (links). These three elements can have specific properties that modify the behavior of the management resources.

Entity definition

Entities properties

Each entities are defined by a set of properties, its type which identify the entity, dans a set of Metadata allowing to extends the definition.

Entity type

An entity is defined by its "type" which is a unique keyword in the application, it identifies one and only one entity in the application.

The type of an entity cannot be empty and a certain number of keywords are prohibited (see the list of atomic types below). As the type identifies the entity it must represent the meaning of this one, it is advised that it be explicit and rather short, because it is a value which is often used.

In addition to the elementary attribute types (see Elementary types) the following keywords cannot be used as a type:

"id", "type", "link" and "entity"
"bean", "list" and "val"
"none" and "null"
Any numeric representation (e.g. "-234").

It is also forbidden to use spaces and other punctuation characters. The only exception are types starting with the string "list/", these types get special treatment (like a global download service) and are reserved for enumeration definition, i.e. fixed lists that do not vary over time.

The underscore "_" character can be used but only inside the string, and it is not recommended because the underscores are duplicated in the XML streams returned by the REST services and this may cause decoding errors.

Entity Domains

The entity is used to represent data that will be served and managed by associated REST services. To identify the source of data relating to an entity, these services use the domain of the entity. Each domain is associated with a mapper (OSGi service) which will be able to use the information declared in the entity to load, create and modify the data it represents.

For example, there is a domain (and mapper) associated with each JDBC DataSource declared in the system. If a "Customer" datasource is declared then a "JDBC:Customer" domain is immediately associated with it. Any entity claiming to belong to the "JDBC:Customer" domain will then be linked to a Table in the underlying database.

Generally a single domain is sufficient to manage an application (this is also recommended). But it is quite possible to see several domains cohabiting in the same application.

Other properties

In addition to its type, an entity is characterized by a version number which makes it possible to identify the current revision of the entity and a date indicating the date of the last modification of the entity. Each modification of the entity is not necessarily linked to an increment of its version number.

Each entity can have access criteria, making it possible to condition the creation, modification, deletion, reading and selection of data. These criteria are expressed in the form of conditions that are applied to the data before each operation. generally these conditions are based on the possession of a specific access right by the current user.

Three final properties are:

readonly defines whether the data is accessible in read-only mode (in this case the access criteria relating to creation, modification or deletion are useless.
lockable indicates that the data can be locked by a user. Locked data can only be modified by the user who locked it until he unlocks it or, depending on the implementation, until a certain period of time has elapsed.
groupType indicates the entity represents "group type" data, which may contain a set of other data. in this case this property designates the entity type of the contained elements.

Added to this is a set of miscellaneous and mostly optional properties. Called metadata, they make it possible to add functionalities, or to modify the behavior of certain services. Here is some entity-related metadata:

autolink: (boolean) indicates that the entity automatically generates associations to any entity that defines an association to the first (allowing to generate reciprocal associations automatically).
reverseLink: (boolean) indicates that the entity automatically generates a "reverse reference" type association to all entities that have an attribute referencing the first entity.
updatable: (boolean) indicates that the entity is timestamped, the date of the last modification of a data is saved with it.
binary: (string) indicates that a document (managed by binary file download service) can be associated with any data. The metadata value indicates the category (i.e. folder on disk) where these documents are stored.

For the needs of JDBC mapping, other meta are added:

table: designates the table to associate with the entity.
idcol: designates the primary key of this table (auto-incremented integer type).
deleteCol: optionally designates the column used to record a logical deletion.
updateCol: designates the name of the column recording the date (timeStamp) of the last modification of the data.
colPrefix: not implemented...
lockCol: not implemented...
lockDateCol: not implemented...
groupTable: not implemented...
groupMinCol: not implemented...
groupMaxCol: not implemented...

Declaration of an entity

Entity definitions are stored in an XML file located in a bundle or on disk in the files/entities/ folder located in the application installation folder. Each file can define one or more entities.

Entity Attributes

Attributes define various properties of the underlying data. Each attribute is identified by a unique (alphanumeric) code within the same entity. The attribute also specifies the "type" of the property value. This type can be an atomic type, see the list below, or a reference to another entity. in this case it is equal to the type of the entity.

NB: The code values follow the same limitations as the "type" (the same keywords are prohibited, see #Type of an entity, punctuation characters are all prohibited, even the underscore and the slash). Only names elementary types can be used as an attribute code even if it is not recommended, but it is quite possible to use an entity type name as an attribute code.

The type of the attribute is parameterized by two properties length and precision which define the characteristics of the data according to the type. an attribute also has the following properties:

readonly (boolean) indicates that the value cannot be changed by users.
test contains Groovy code executed when a value is accessed or modified.
name represents the label of the tetl attribute that can be presented to the user, this property, if it is absent from the declaration, is generated as translatable data.

The label (name) of an attribute can be loaded from the Translatable Properties service. In the "entities.properties" file, it is obtained by the key: <entity type>.<attribute code>

Meta data is added to these properties:

logs: indicates that any value modification of this attribute must be logged by the "log" entity.
colrank: gives a placement order for the attribute in the tabular representations.
colsize: gives an indicative size (in "pixel") for tabular representations.
visible: indicates whether the attribute should be presented in a tabular representation by default.
reverseLink: automatically generates a "reverse reference" type association on the entity that is referenced by this attribute.
col: as part of the JDBC mapper this meta indicates the name of the column that stores this attribute in the table associated with the entity.
crypt: (string, the current implementation only support "mapper".) Indicates that the data should be encrypted in the store. Data encryption/decryption is the responsibility of the mapper associated with the entity's domain. The use of this metadata has an impact on the use of the data in the selection criteria, being encrypted the tests of equality or more generally of comparison with another data (not encrypted) no longer has any meaning.

Elementary types

Are called elementary type, or atomic, any type which is not the type of an entity. here is the list of basic types and how they are handled:

boolean: 0/1 binary format.
integer: integer format, Length = maximum value (0 if unlimited)
range: integer format, Length = Max value, Precision = Min value. If Max < Min then no upper limit.
float: real number format, Length = max value, Precision = max precision.
date: date format, Precision < 0 for dates representing days (hour = 0) and > 0 for dates representing only Hours.
string: character string format, Length = maximum size. If Length is less than or equal to 0 then the string size is unlimited.
translate: this type does not match any actual data. The value of this attribute is determined according to the language of the current user and a code built from the data type. See Translatable data.
icon: integer format, Length = series number. Uses a dedicated web service to load an image that graphically represents an enumerated value.
url: character string with a particular format (not implemented).

Beyond these elementary types any type which is not a reference to an entity is considered as an integer if precision > 0. In this case the value of the attribute is guaranteed to be greater than or equal to precision. If length > precision then the value is guaranteed to be less than or equal to length. Otherwise the value is considered as a string and if length > 0 then this string is truncated at the designated length.

The Associations (Links) of entities

Associations define relationships between two entities. The associations are oriented, ie to represent a relation which would link 2 entities in both directions, each of these entities must declare the association.

An association is identified by a code that is unique within the entity. The code of an association cannot be the same as the code of an attribute of the same entity, otherwise the association will not be accessible either by REST services or in reference chains.

The association also has a type which is the type of the target entity. As well as access criteria on creation or selection operations.

As for attributes each association has a label (name) which can be automatically generated from the translatable properties service. In the "entities.properties" file, it is obtained by the key: <entity type>.link.<attribute code>

In addition the following metadata can be assigned to an association:

reverseLink: means an association is actually a reverse reference. The value of this metadata designates the attribute of the target entity that serves as a reference.
table, sourceCol and destCol designate, within the framework of an entity linked to a JDBC domain, the joining table as well as the columns used to identify the source and target entities of the association.

Declaration of an association

code: Relationship name
type: Type of the entity returned by the relationship
sourceCol: name of the column of the association table which will be linked with the primary key of the table in which the link is declared
destCol: name of the chaining column between the association and the table defined by the type of entity
table: association table name

Declaration of a simple relation

Initial scheme:

Consider a table TABLE A whose declared entity is entityA, having a Primary key is set to COLA_ID.
Consider a table TABLE B whose declared entity is entityB, having a Primary key set to COLB_ID and referencing TABLE A by column COLB_COLA_ID whose declared attribute is attribute_entityA.

Declaration of the link:

The link is declared in the entity entityA and allows, from a record in table A, to reread all the linked records in table B.

It will have the following form:

<link type="entityB" 
    code="MyBEntities" 
    readonly="false">
    <metadata>
        <reverseLink>attribute_entityA</reverseLink>
    </metadata>
</link>

Where:

type is the name of the "referencing" entity (in our case entityB),
code is the name you want to give to the relation,
reverseLink is the attribute name of the "referencing" entity that defines the referencing (in our case: attribute_entityA)

Search Criteria representation

The Search Criteria are used to apply a condition on the elements of an Entity. This may be used for data selection, validation of advanced conditions such as the expression of the access rights relative to the CRUD operations on data. The current implementation offer a list of Search criteria for most of the common condition cases, this list is extended from time to time...

Each search criteria is represented by a Java Class and used in the java code, it may also be expressed in XML, JSON and in a textual form.

In the XML representation of all criteria, any XML attribute may be replaced by a sub-tag with the same name. For instance: <equals attribute="code" value="zzz"/> is equivalent to <equals><attribute>code</attribute><value>zzz</value></equals>.

In JSON and the XML attributes commonly named "attribute" may be shortened in "a", "secondAttribute" in "sa", "value" in "v" and "casesensitive" is "case" or even "cs". So the previous example is also equivalent to the representation <equals a="code" v="zzz"/>.

JSON format is case insensitive, which means that any criteria name or parameter may be written in any combination of lowercase or uppercase letters. Moreover the JSON format add a lot of shorten keywords. For instance all in Link related criteria name the "link" word may be shortened as "l", then "linkequals" may be written "lequals". All order operator like "greaterthan" or "greaterstrict" may be shortened in "gt" or "gs"...

Composed Criteria

Theses operators allow to logically combine other criteria to produce complex conditions.

not

Represent the negation of the contained condition. The value of this condition is the reciprocal of the value of the contained element.

java: NotCriteria
XML: <not> ... </not>
JSON: { "not": ... }
Textual 1: not ...
Textual 2: ! ...

Define a conjunctive set of conditions. The content of this element is a sequence of conditions, its value is true if at least one of these condition is true.

lava: OrCriteria
XML: <or> ... </or>
JSON: { "or": [...] }
Textual 1: ... or ...
Textual 2: ... | ...

and

Define a disjunctive set of conditions. The content of this element is a sequence of conditions, its value is true if and only if all of these condition are true.

java: AndCriteria
XML: <and> ... </and>
JSON: { "and": [... ] }
Textual 1: ... and ...
Textual 2: ... & ...

Constants criteria

These operators always return the same value in any contexts.

true

Represents a boolean constant true value. Used in a selection operation, this value is identical to an empty selection constraint, all results will be selected.

java: ConstantCriteria.TRUE
XML: <true/>, the web-services /data/* also accept <all/> as a valid representation for this criteria.
JSON: { "constant": "true" }
Textual: true

false

Represents a boolean constant false value.

java: ConstantCriteria.FALSE
XML: <false/>
JSON: { "constant": "false" }
Textual: false

constant

Represents a boolean constant value. Its value is defined by its unique parameter which value may be "false" or "true".

java: ConstantCriteria
XML: <constant>...</constant>
JSON: { "constant": "..." }
Textual 1: true
Textual 2: false

Attributes value testing

These following criteria are used to test some attributes of the current Entity. Most of them use a parameter named "attribute". It defines the Entity attribute to be used to perform the test. This "attribute" may be a reference line, a list of attributes names separated with dot, where the first name is an attribute from the relative entity, and all following ones are issued from the entities in relation with each other. In the end the value tested here is the actual value of the last attribute in the reference line.

For instance: "reporter.client.name" of the current Entity "Issue" is the "name" of the "Client" associated to the "User" which is the "reporter" of the "Issue".

Some of these criteria accept that the reference line contain an, unique, link code. In that case the condition execution will use the correspondent link criteria. It is important to mention that only one link code may actually be used in the reference line, chained association is not currently supported.

For instance: "reporter.profiles.code" include the link code "profiles", the test will be done on the "code" of all the "Profiles" linked to the "reporter" User.

equals

Test if the given attribute value is equal to the given constant value. The attribute reference line may include a link code.

If the constant value is a numeric value the "intval" parameter name should be used in place of the "value" attribute. If the constant value is a string then the boolean parameter "casesensitive" may be used to define if the test is sensible to the case or not, by default it is.

The two parameters "intval" and "value" are exclusives, "intval" define a numerical (integer) have priority on the "value" parameter. And "casesensitive" should be only used in conjunction with "value" and a a value of "false".

java: EqualCriteria
XML: <equals attribute="x" intval="0"/> or <equals attribute="x" value="text" casesensitive="false"/>
JSON: { "equals": { "attribute": "x", "intval": 0, "value": "..." } }
Textual 1: x == 0
Textual 2: x = "..." (If case insensitive)

equalsic

This criteria is a simplified version of the above equals criteria with casesensitive parameter forced to "false". It tests the equality of a constant character string to the value of the designated attribute without taking into account case (difference between upper and lower case letters). Just like the equals criteria it support reference line with a link code.

The parameter "value" define the constant value to test against the attribute value.

java: EqualICCriteria
XML: <equalsic attribute="x" value="0" />
JSON: { "equalsic": { "attribute": "x", "value": "..." } }
Textual: x = "..."

equalsattributes

Tests if the values of the two attributes are equals.

The parameter "secondAttribute" define the second Entity attribute to be used to perform the test. This "secondAttribute" may also be a reference line, but only one of them may include a link code in the reference line. Using multiples link code in same, or both of the reference lines is not currently supported.

If the attributes values are comparable as string of characters, then the boolean parameter "casesensitive" may be used to state if the test must be sensible to the case or not.

java: AttributeEqualsCriteria
XML: <equalsattributes attribute="x" secondAttribute="y" />
JSON: { "equalsattributes": { "attribute": "x", "secondattribute": "y" } } or in short { "eqa": { "a": "x", "sa": "y" } }
Textual: x = y or x == y if case sensitive

lowerstrictAttributes

Test the values of the two attributes, and validate that the value of the first attributes is strictly lower to the value of the second one.

The parameter "secondAttribute" define the second Entity attribute to be used to perform the test. Just like the "attribute" parameter it may be a reference line, but this criteria does not allow to use a link code in any of the used reference lines, yet.

java: AttributeLowerCriteria
XML: <lowerstrictAttributes attribute="x" secondAttribute="y" />
JSON: { "lowerstrictAttributes": { "attribute": "x", "secondAttribute": "y" } }
Textual: x < y

lowerthanAttributes

Test the values of the two attributes, and validate that the value of the first attributes is lower or equals to the value of the second one.

java: AttributeLowerOrEqualsCriteria
XML: <lowerthanAttributes attribute="x" secondAttribute="y" />
JSON: { "lowerthanAttributes": { "attribute": "x", "secondAttribute": "y" } }
Textual: x <= y

isnull

Test if the given attribute value is null. This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

java: IsNullCriteria
XML: <isnull attribute="x" />
JSON: { "isnull": "x" }
Textual: x is null

istrue

Test if the current value of the given attribute is a boolean value and if this value is "true". This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

java: IsTrueCriteria
XML: <istrue attribute="x" />
JSON: { "istrue": "x" }
Textual: x is true

lowerthan

Test if the numerical value of the given attribute is lower or equal to the given constant value. This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

The parameter "value" define the constant value to test against the attribute value.

java: LowerThanCriteria
XML: <lowerthan attribute="x" value="..." />
JSON: { "lowerthan": { "attribute: "x", "value": "..." } }
Textual: x <= ...

greaterthan

Test if the numerical value of the given attribute is greater or equal to the given constant value.

The parameter "value" define the constant value to test against the attribute value.

java: GreaterThanCriteria
XML: <greaterthan attribute="x" value="..." />
JSON: { "greaterthan": { "attribute: "x", "value": "..." } }
Textual: x >= ...

lowerstrict

Test if the numerical value of the given attribute is lower than the given constant value. This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

The parameter "value" define the constant value to test against the attribute value.

java: LowerStrictCriteria
XML: <lowerstrict attribute="x" value="..." />
JSON: { "lowerstrict": { "attribute: "x", "value": "..." } }
Textual: x < ...

greaterstrict

Test if the numerical value of the given attribute is greater than the given constant value.

The parameter "value" define the constant value to test against the attribute value.

java: GreaterStrictCriteria
XML: <greaterstrict attribute="x" value="..." />
JSON: { "greaterstrict": { "attribute: "x", "value": "..." } }
Textual: x > ...

starts

Test if the given attribute value, which must be a string compatible data, starts with the given prefix.

The parameter "value" define the prefix string to check.

The parameter "casesensitive" define if the test must be case sensitive or not. The default value of this parameter is false.

java: StartCriteria
XML: <starts attribute="x" value="..." casesensitive="true" />
JSON: { "starts": { "attribute: "x", "value": "..." } }
Textual: x !: 0 or x !:: 0 if sensitive to the case.

ends

Test if the given attribute value, which must be a string compatible data, ends with the given suffix.

The parameter "value" define the suffix string to check.

The parameter "casesensitive" define if the test must be case sensitive or not. The default value of this parameter is false.

java: EndCriteria
XML: <ends attribute="x" value="..." />
JSON: { "ends": { "attribute: "x", "value": "..." } }
Textual: x :! 0 or x ::! 0 if sensitive to the case.

contains

Test if the given attribute value, which must be a string compatible data, contains with the given text string.

The parameter "value" define the sub text to check.

The parameter "casesensitive" define if the test must be case sensitive or not. The default value of this parameter is false.

java: ContainCriteria
XML: <contains attribute="x" value="..." />
JSON: { "contains": { "attribute: "x", "value": "..." } }
Textual: x : 0 or x :: 0 if sensitive to the case.

before

Test if the given attribute value, which must be a Date or compatible data, is set to an instant which take place before the instant defined by the combination of the temporal parameters. This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

All dates are expressed in GMT time zone.

The parameter "value" define an absolute date constant. If the other parameter are used this date will be altered. The default value is the current time.

If parameter "trunc" is true then only the Date part of the instant will be tested (the Time part will be ignored).

The parameter "years" define the year to compare with. If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "months" define the month in the year to compare with (from 1 to 12). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "days" define the day in the month to compare with (from 1 to 31). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "hours" define the hours to compare with (from 0 to 23). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "minuts" define the minutes to compare with (from 0 to 59). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

java: BeforeCriteria
XML:

 <before attribute="x" value="1970-01-01T00:00:00.0000Z" trunc="true" 
         years="1" months="2" days="3" hours="4" minuts="5" />

JSON:

 { "before": { "attribute: "x", 
                "value": "1970-01-01T00:00:00.0000Z", 
                "trunc": "true" , 
                "years": 1, 
                "months": 2, 
                "days": 3, 
                "hours": 4, 
                "minuts": 5 
  }           }

Textual: x <</ '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M
Textual2: x << '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M if the date is not truncated. Note: The textual representation of the increments may use the short representation "+1y" or "-1y", or any combination of extended representation "+2years" with or without spaces between the number and the unit, like this "-3 years". The accepted unit names are "y", "yr", "yrs", "year, "years", "m", "mth", "mths", "month", "months", "d", "day", "days", "h", "hr", "hour", "hours", "M", "mn", "mns", "minute", "minutes". They are all case insensitive, except the "M" standing for minutes. In the textual representation, if the same unit is use twice then the incremental values are combined, e.g. "+2y -3 years" is converted in a -1 year increment. The order of the date increments is undefined.

after

Test if the given attribute value, which must be a Date or compatible data, is set to an instant which take place after the instant defined by the combination of the temporal parameters. This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

All dates are expressed in GMT time zone.

The parameter "value" define an absolute date constant. If the other parameter are used this date will be altered.

If the parameter "trunc" is true then only the Date part of the instant will be tested (the Time part will be ignored).

The parameter "years" define the year to compare with. If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "months" define the month in the year to compare with (from 1 to 12). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "days" define the day in the month to compare with (from 1 to 31). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "hours" define the hours to compare with (from 0 to 23). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "minuts" define the minutes to compare with (from 0 to 59). If a "value" is specified then this parameter define a time shift, positive or negative, from the given date.

java: AfterCriteria
XML:

 <after attribute="x" value="1970-01-01T00:00:00.0000Z" trunc="true" 
         years="1" months="2" days="3" hours="4" minuts="5" />

JSON:

 { "after": { "attribute: "x", 
              "value": "1970-01-01T00:00:00.0000Z", 
              "trunc": "true", 
              "years": 1, 
              "months": 2, 
              "days": 3, 
              "hours": 4, 
              "minuts": 5 
 }          }

Textual1: x >>/ '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M
Textual2: x >> '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M if the date is not truncated. Note: The textual representation of the increments may use the short representation "+1y" or "-1y", or any combination of extended representation "+2years" with or without spaces between the number and the unit, like this "-3 years". The accepted unit names are "y", "yr", "yrs", "year, "years", "m", "mth", "mths", "month", "months", "d", "day", "days", "h", "hr", "hour", "hours", "M", "mn", "mns", "minute", "minutes". They are all case insensitive, except the "M" standing for minutes. In the textual representation, if the same unit is use twice then the incremental values are combined, e.g. "+2y -3 years" is converted in a -1 year increment. The order of the date increments is undefined.

between

Test if the given attribute value, which must be a Date or compatible data, is set to an instant which take place between the instants defined by the combination of the temporal parameters. This criteria does not allow to use a link code in the reference line defining the "attribute" parameter.

All dates are expressed in GMT time zone.

The parameter "before" define an absolute date constant used as the higher limit of the instant interval. If the other parameter are used this date will be altered.

The parameter "after" define an absolute date constant used as the lower limit of the instant interval. If the other parameter are used this date will be altered.

If the parameter "trunc" is true then only the Date part of the instant will be tested (the Time part will be ignored).

The parameter "afteryears" define the year to compare with as the lower limit of the instant interval. If a "after" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "aftermonths" define the month in the year to compare with (from 1 to 12) as the lower limit of the instant interval. If a "after" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "afterdays" define the day in the month to compare with (from 1 to 31) as the lower limit of the instant interval. If a "after" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "afterhours" define the hours to compare with (from 0 to 23) as the lower limit of the instant interval. If a "after" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "afterminuts" define the minutes to compare with (from 0 to 59) as the lower limit of the instant interval. If a "after" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "beforeyears" define the year to compare with as the higher limit of the instant interval. If a "before" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "beforemonths" define the month in the year to compare with (from 1 to 12) as the higher limit of the instant interval. If a "before" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "beforedays" define the day in the month to compare with (from 1 to 31) as the higher limit of the instant interval. If a "before" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "beforehours"define the hours to compare with (from 0 to 23) as the higher limit of the instant interval. If a "before" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

The parameter "beforeminuts" define the minutes to compare with (from 0 to 59) as the higher limit of the instant interval. If a "before" parameter is specified then this parameter define a time shift, positive or negative, from the given date.

java: BetweenCriteria
XML:

 <between attribute="x" trunc="true" 
          after="1970-01-01T00:00:00.0000Z"
          afteryears="1" aftermonths="2" afterdays="3" afterhours="4" afterminuts="5"
          before="1970-01-01T00:00:00.0000Z"
          beforeyears="1" beforemonths="2" beforedays="3" beforehours="4" beforeminuts="5" />

JSON:

 { "between": { "attribute: "x", 
                "trunc": "true", 
                "after": "1970-01-01T00:00:00.0000Z", 
                "afteryears": 1,
                "aftermonths": 2, 
                "afterdays": 3, 
                "afterhours": 4, 
                "afterminuts": 5,
                "before": "1970-01-01T00:00:00.0000Z", 
                "beforeyears": 1,
                "beforemonths": 2, 
                "beforedays": 3, 
                "beforehours": 4, 
                "beforeminuts": 5 
  }          }

Textual1:

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M << x << '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M >> x >> '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M

Textual2: if the date is truncated

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M <</ x <</ '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M >>/ x >>/ '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5M

Note: The textual representation of the increments may use the short representation "+1y" or "-1y", or any combination of extended representation "+2years" with or without spaces between the number and the unit, like this "-3 years". The accepted unit names are "y", "yr", "yrs", "year, "years", "m", "mth", "mths", "month", "months", "d", "day", "days", "h", "hr", "hour", "hours", "M", "mn", "mns", "minute", "minutes". They are all case insensitive, except the "M" standing for minutes. In the textual representation, if the same unit is use twice then the incremental values are combined, e.g. "+2y -3 years" is converted in a -1 year increment. The order of the date increments is undefined.

isin

This condition is used to perform a sub-selection on an already known list of elements by listing their internal ID.

The mandatory parameter "ids" is the list of Internal IDs of objects to return, each ones separated by comma.

If the optional parameter 'attribute" is used, the the test is performed along with the element ID designated by the value of this attribute. This parameter can be a reference line but it can not include link codes in it.

For instance ids = "1,2,3" will only select the object with ID 1, 2 or 3.

Please note that using large list of ID number may cause some performances issues and overload the HTTP limitations. Consider to use the /data/{entity}/{id} web-service which support to select a list of resource using a sum of ids. for instance, a call to /data/issue/1+2+3 is equivalent to /data/issue?criteria=<isin ids="1,2,3"/>

java: IdInListCriteria
XML: <isin attribute="x" ids="1,2,3" />
JSON: { "isin": [ 1, 2, 3] } or { "isin": { "attribute": "x", "ids": [ 1, 2, 3] }
Textual : @id in 1, 2, 3 or x in 1, 2, 3

Links testing

linkto

Test that the relative entity, or the entity referenced through the given attribute is linked to a unique given element (ID). This criteria can provide multiples identical, duplicated, results.

Note that the negation of this criteria is not the common meaning of "Not linked to" it does not return all the data not linked to the given element ID, but the data linked to other elements, this include any data which may be linked with the designated element but which is also linked to another one, and this exclude any data with no link at all.

The parameter "linkCode" is required and is apply to the entity referenced by the optional "attribute" parameter. By default the link must be defined in the selected entity. The reference line defined by the "attribute" parameter can not include another link code.

The parameter "id" define the internal ID of the linked element.

java: LinkCriteria
XML: <linkto linkCode="y" attribute="x" id="0" />
JSON: { "linkto": { "linkCode": "y", "attribute": "x", "id": 0 } }
Textual: x -> y = 0

unlinkto

Tests for the absence of a link with the designated element. This condition is validated if there is no link with the targeted element, this is verified if the referenced one is not linked to any data or if it is linked to any other elements. See the above criteria linkto for details.

The parameter "id" define the internal ID of the non linked element.

java: UnlinkCriteria
XML: <unlinkto code="c" attribute="x" id="0" />
JSON: { "unlinkto": { "code": "c", "attribute": "x", "id": 0 } }
Textual: x !> c = 0

linkequals

Perform an equality test through a linked entity. This allow to select element which are linked to any other elements which validate the equality.

The parameter "reference" is optional it define the Entity to be used to perform the test. It may be a reference line, but it can not include any other link code.

The mandatory parameter "linkCode" define the link code of an association. If the "reference" parameter is used then the link is relative to the referenced entity.

The parameter "attribute" is also optional, if define the attribute to be used to perform the equality test. This attribute must correspond to targeted entity through the used link. It may be a reference line but it can not include another link code.

The parameter "value" define the constant value used to perform the equality test. If the "value" parameter is not used the parameter "secondAttribute" may define another attribute relative to the selected entity (i.e. not to the entity targeted by the link !). It may be a reference line, but it can not include any other link code. If define this is the value of the "secondAttribute" which will be compared against the value of the "attribute".

At last if the compared value are strings of character the boolean parameter "casesensitive" may be used to state if the comparison must be sensitive the the characters case.

java: LinkEqualCriteria
XML: <linkequals reference="r" linkCode="c" attribute="x" value="0" />
JSON: { "linkequals": { "reference": "r", "linkCode": "c", "attribute": "x", "value": "..." } }
Textual: r -> c x = "..."

linkstarts

Test if the value of an attribute start with the given prefix, through a linked entity. This allow to select elements which are linked to any other element which validate the equality.

The parameter "reference" is optional it define the Entity to be used to perform the test. It may be a reference line, but it can not include any other link code.

The mandatory parameter "linkCode" define the link code of an association. If the "reference" parameter is used then the link is relative to the referenced entity.

The parameter "attribute" is also optional, if define the attribute to be used to perform the test. This attribute must correspond to targeted entity through the used link. It may be a reference line but it can not include another link code.

The parameter "value" define the constant value used to perform the equality test.

The boolean parameter "casesensitive" may be used to state if the comparison must be sensitive the the characters case or not. The default value is case insensitive.

java: LinkStartCriteria
XML: <linkstarts reference="r" linkCode="c" attribute="x" value="0" />
JSON: { "linkstarts": { "reference": "r", "linkCode": "c", "attribute": "x", "value": "..." } }
Textual: r -> c x !: "..."

linkends

Test if the value of an attribute ends with the given suffix, through a linked entity. This allow to select elements which are linked to any other element which validate the equality.

The parameter "reference" is optional it define the Entity to be used to perform the test. It may be a reference line, but it can not include any other link code.

The mandatory parameter "linkCode" define the link code of an association. If the "reference" parameter is used then the link is relative to the referenced entity.

The parameter "value" define the constant value used to perform the equality test.

The boolean parameter "casesensitive" may be used to state if the comparison must be sensitive the the characters case or not. The default value is case insensitive.

java: LinkEndCriteria
XML: <linkends reference="r" linkCode="c" attribute="x" value="0" />
JSON: { "linkends": { "reference": "r", "linkCode": "c", "attribute": "x", "value": "..." } }
Textual: r -> c x :! "..."

linkcontains

Test if the value of an attribute conains with the given sub-string, through a linked entity. This allow to select elements which are linked to any other element which validate the equality.

The parameter "reference" is optional it define the Entity to be used to perform the test. It may be a reference line, but it can not include any other link code.

The mandatory parameter "linkCode" define the link code of an association. If the "reference" parameter is used then the link is relative to the referenced entity.

The parameter "value" define the constant value used to perform the equality test.

The boolean parameter "casesensitive" may be used to state if the comparison must be sensitive the the characters case or not. The default value is case insensitive.

java: LinkContainCriteria
XML: <linkcontains reference="r" linkCode="c" attribute="x" value="0" />
JSON: { "linkcontains": { "reference": "r", "linkCode": "c", "attribute": "x", "value": "..." } }
Textual: r -> c x : "..."

linkgreaterstrict

Test if the value of an attribute is strictly greater than the given constant value, through a linked entity. This allow to select elements which are linked to any other element which validate the equality.

The parameter "reference" is optional it define the Entity to be used to perform the test. It may be a reference line, but it can not include any other link code.

The mandatory parameter "linkCode" define the link code of an association. If the "reference" parameter is used then the link is relative to the referenced entity.

The parameter "value" define the constant value used to perform the equality test.

java: LinkGreaterStrictCriteria
XML: <linkgreaterstrict reference="r" linkCode="c" attribute="x" value="0" />
JSON: { "linkgreaterstrict": { "reference": "r", "linkCode": "c", "attribute": "x", "value": "..." } }
Textual: r -> c x : "..."

linkgreaterthan

Test if the value of an attribute is greater or equals to the given constant value, through a linked entity. This allow to select elements which are linked to any other element which validate the equality.

The parameter "reference" is optional it define the Entity to be used to perform the test. It may be a reference line, but it can not include any other link code.

The mandatory parameter "linkCode" define the link code of an association. If the "reference" parameter is used then the link is relative to the referenced entity.

The parameter "value" define the constant value used to perform the equality test.

java: LinkGreaterThanCriteria
XML: <linkgreaterthan reference="r" linkCode="c" attribute="x" value="0" />
JSON: { "linkgreaterthan": { "reference": "r", "linkCode": "c", "attribute": "x", "value": "..." } }
Textual: r -> c x : "..."

Specific criteria

idequals

Test the internal ID of the selected Entity data against the given value.

The parameter "id" (integer) is required and defines a constant numerical, positive value, representing the internal ID to test.

java: IdEqualCriteria
XML: <idequals id="0"/>
JSON: { "idequals": 0 }
Textual: @id = 0

idgreaterstrict

Test the internal ID of the selected Entity data against the given value.

The parameter "id" (integer) is required and defines a constant numerical, positive value, representing the internal ID to test.

java: IdGreaterStrictCriteria
XML: <idgreaterstrict id="0"/>
JSON: { "idgreaterstrict": 0 }
Textual: @id > 0

idgreaterthan

Test the internal ID of the selected Entity data against the given value.

The parameter "id" (integer) is required and defines a constant numerical, positive value, representing the internal ID to test.

java: IdGreaterThanCriteria
XML: <idgreaterthan id="0"/>
JSON: { "idgreaterthan": 0 }
Textual: @id >= 0

idlowerstrict

Test the internal ID of the selected Entity data against the given value.

The parameter "id" (integer) is required and defines a constant numerical, positive value, representing the internal ID to test.

java: IdLowerStrictCriteria
XML: <idlowerstrict id="0"/>
JSON: { "idlowerstrict": 0 }
Textual: @id < 0

idlowerthan

Test the internal ID of the selected Entity data against the given value.

The parameter "id" (integer) is required and defines a constant numerical, positive value, representing the internal ID to test.

java: IdLowerThanCriteria
XML: <idlowerthan id="0"/>
JSON: { "idlowerthan": 0 }
Textual: @id <= 0

hasright

Test if the current, or the given, user possess the given access Right number.

The parameter "attribute" may be a reference line but it can not include a link code. This is an optional parameter if the tested entity is the "User" entity. If not this is a required parameter, representing an attribute which is an User. The special "." indicate that this test is performed on the currently connected user, this option is independent from the actual tested entity.

The parameter "right" (integer) defines the access Right number (ID) to test. The list of the list of defined rights on the platform can be acceded through the web-service : /data/right

The optional parameter "param" can be used in combination with a specific access right number, its value will be tested against the actual right "param" value. This value could be a integer constant or defined as an attribute reference line, or with the special character ".". If a reference line is used then the corresponding right "param" will have to be equal to the current value of this attribute. If the dot special character is used the the integer value will be the internal ID of the selected entity element.

XML: <hasright attribute="." right="123" param="0"/>
JSON: { "hasright": { "attribute": ".", "right": 123, "param": 0 } }
Textual: . ? 123:0

currentuser

Compares the value of an attribute of the element to select to the value of an attribute of the current user, or, failing that, to the ID of the current user. If the current user is not accessible then this condition returns false.

The parameter "attribute" define the Entity attribute to be used to perform the test.

The optional parameter "userAttribute" defines which user attribute will be compared to the attribute to test. If no "userAttribute" is specified then the integer identifier of the current user will be compared to the value of the specified "attribute".

Both "attribute" and "userattribute" may be references line, but no Link code may be used in these references. The value of this attribute must be an integer or a reference to another data (i.e. an integer too).

The optional "linkCode" parameter, if used than the test will be performed against the given link, this link must target the entity represented by "userattribute" or by default to the User entity. If the "attribute" parameter is used than this is the value of this parameter which will be used a source of this link.

For instance, If an Entity "Issue" allow to define an attribute reference line "reporter.client" referencing the Client entity of the User who reported the issue. If the Client entity define a link named "employees" targeting the User(s) which are member of this organisation then the following criteria will select all the issues where the current is an employee of the same client than the issue reporter:

<currentuser linkCode="employees" attribute="reporter.client" />

java: CurrentUserCriteria
XML: <currentuser userAttribute="x" attribute="y"/>
JSON: { "currentuser": { "userAttribute": "x", "attribute": "y" } }
Textual: @user x = y or @user x -> c = y

changed

Test if the referenced element has been changed during the given interval of time. The "before" and "after" parameters are optionals, if omitted the current time will be used. The optional "attribute" parameter may be a reference line, but no link code may be included if the line. If specified the value of the "attribute" must be an Entity using the "updatable" MetaData.

All date are expressed in GMT time zone.

The parameter "before" define an absolute date constant used as the higher limit of the instant interval. If the other parameter are used this date will be altered.

The parameter "after" define an absolute date constant used as the lower limit of the instant interval. If the other parameter are used this date will be altered.

If the boolean parameter "trunc" is true then only the Date part of the instant will be tested (the Time part will be ignored).

java: ChangedCriteria
XML:

 <changed attribute="x" trunc="true" 
          after="1970-01-01T00:00:00.0000Z"
          afteryears="1" aftermonths="-2" afterdays="3" afterhours="-4" afterminuts="5"
          before="1970-01-01T00:00:00.0000Z"
          beforeyears="1" beforemonths="2" beforedays="3" beforehours="4" beforeminuts="5" />

JSON:

 { "changed": { "attribute: "x", 
                "trunc": "true", 
                "after": "1970-01-01T00:00:00.0000Z", 
                "afteryears": 1,
                "aftermonths": -2, 
                "afterdays": 3, 
                "afterhours": -4, 
                "afterminuts": 5,
                "before": "1970-01-01T00:00:00.0000Z", 
                "beforeyears": 1,
                "beforemonths": 2, 
                "beforedays": 3, 
                "beforehours": 4, 
                "beforeminuts": 5 
 }          }

Textual:

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n << x.@date << '1971-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n

or the following to test the currently selected element:

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n << @date << '1971-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n

which is also equivalent to:

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n << << '1971-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n

Textua2: if the date is truncated:

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n <</ x.@date <</ '1971-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n

or the following to test the currently selected element:

 '1970-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n <</ <</ '1971-01-01T00:00:00.0000Z' +1y +2m +3d +4h +5n

deleted

Test if the referenced element is deleted (i.e. test if this element is using soft deletion). The "attribute" parameter is optional, if it is used it must refer an Entity supporting soft deletion. No Link code may be used in the reference line.

java: DeletedCriteria
XML: <deleted attribute="x" />
JSON: { "deleted": { "attribute": "x" } }
Textual : !! x

subst

This special criteria can be used as a place holder in a template document, or if the code parameter is set to one of the reserved code it can be replaced by the correspond access right test.

The required parameter "code" (string) defines the substitution code that will be used to replace this criterion when evaluating the condition.

Some reserved code may be used to substitute this condition with the corresponding access right test:

entity.create: refer to the creation right of the given entity.
entity.update: refer to the update right of the given entity.
entity.list: refer to the list right of the given entity.
entity.read: refer to the read right of the given entity.
entity.delete: refer to the delete right of the given entity.
entity.attribute.update: refer to the update right of the given entity's attribute.
entity.attribute.read: refer to the read right of the given entity's attribute.
entity.link.create: refer to the create/delete right of the given entity's association link.
entity.link.list: refer to the delete right of the given entity's association link.
java: SubstCriteria
XML: <subst code="xxx" />
JSON: { "subst": "xxx" }
Textual: # xxx #

pregen

This condition contain a hard coded condition, which must take into account the mapper syntax and its internal constraints. It must be reserved to very specific usages that may not be implemented by any combination of other criteria.

Please note, this type of condition is not portable and should only be used locally, for very specific uses.

java: PreGeneratedCriteria
XML: <pregen>...</pregen>
JSON: { "pregen": "..." }
Textual: {...}

Entity manipulation API

The following class implements the notion of entity: com.arcadsoftware.metadata.MetaDataEntity

To obtain an entity defined on the system, the static method "getEntity(String type)" is used. For example, to obtain the "incident" entity, we use the following code:

MetaDataEntity incidentEntity = MetaDataEntity.getentity("incident");   //$NON-NLS-1$

If the "incidentEntity" variable is null then the corresponding entity is not declared on the system. From this variable you can access the information declared by the entity (list of attributes, associations, etc.) but you can also manipulate the data linked to it using the methods starting with "data".

Thus the following code is used to retrieve all the "incidents" accessible to the system:

BeanMapList indidentsList = incidentEntity.dataSelection();

A bundle wishing to manipulate an entity only has the "com.arcadsoftware.metadata" package to import. Obtaining the entity requires a call to an entity registry (implemented in the "com.arcadsoftware.metadata.registry.xml" bundle) which keeps in memory all the entities declared on the system.

Notion of "reference line"

A reference is an attribute whose type is the type of another entity. Its value is therefore a reference (usually an ID) of a data of this entity. The system allows to bind the attributes to load, and manipulate the values of the attributes of the referenced entity. To do this, use the list of codes allowing access to the desired value, connected by dots ".".

So user.civility.label designates the "label" attribute of the referenced entity via the "user" then "civility" attribute.

The "getReferenceLine" method of the MetaDataEntity class makes it possible to decode such a path. The result of this method provides access to the terminal attribute. Thus all services that use attribute codes (such as selection services) allow the use of reference lines to load linked data in 1 call.

Java client access API

The Client REST can load entities and access data using the class: com.arcadsoftware.metadata.client.DataAccess

This class is used to list, read, create, modify or delete data. It also allows you to load an entity, properties files for translation or binary files. For this the client program only needs the "com.arcadsoftware.beanmap" and "com.arcadsoftware.metadata" bundles.

On the client side, the MetaDataEntity class is accessible, the code below illustrates the loading of the "incident" entity:

MetaDataEntity incidentEntity = new DataAccess(activator,"http://localhost:5252/","admin@quadra","quadra").getentity("incident");

You can also use the data* methods they relly on the DataAccess object which generated the entity object. Note that for most data manipulations the entity itself is not required, only knowledge of its "type" and the codes of these attributes is sufficient. The results take the form of BeanMaps.

Example of a simple entity

The example below describes the "right" entity as declared by the "com.arcadsoftware.metadata.rights" bundle:

<entity type="right" domain="mem:rights" readonly="true" version="1">
    <attribute code="code" type="string" listable="true" />
    <attribute code="name" type="translate" listable="true" />
    <attribute code="category" type="rightcategory" listable="true" />
</entity>

The domain that manages this entity is called "mem:rights" it is a mapper using a table in memory and loading the rights defined in XML files. This is a special map exclusively reserved for storing access rights.

Access rights are data that cannot be modified by the user (hence the readonly="true" property).

This entity defines 3 attributes:

a "code" attribute whose values are character strings.
a "name" attribute of type "translate". the translate type is special. The values of this attribute will be stored in a properties file and it will be injected into the data on demand depending on the language of the user.
a "category" attribute which is a reference to another entity whose type is "rightcatergory".
The "listable" option indicates that all these attributes are by default returned in the result lists when a selection is made.

Entities right management

Each entities may define the user access Rights required to perform any operation on them. Basically there is 5 kind of access management by the entities: The List access, the Read access, the Creation access, The Update access and the Delete access, each one corresponding to a specific web-service call:

List correspond to a GET on /data/{type}
Read correspond to a GET on /data/{type}/{id}

Move over each Attributes may define a specific Read and Update access right, and the Links may define Create and List access Rights.

Declaration

To declare the access rights, the Entity declaration file (entities.xml) must contain an <rights> tag. This tag must be placed under the <entity>, the <attribute> or the corresponding <link> tag. This tag may contain the following sub-tags: <create>, <delete>, <list>, <read> and <delete> tag. Each one of these tag will contain an XML representation of ISearchCriteria. This expression represent the contition that the currently connected user and the acceded data must fulfill in order to perform the corresponding operation.

Most of the time this search criterion will be limited to the verification of a specific Right number, this test imply the usage of the ISearchCriteria "hasright", in xml:

<create>
    <hasright attribute="." right="666" />
</create>

Where, "." stand for "the currently connected user, and 666 is the specific access Right declared in one of the rights.xml files somewhere on the platform. This declaration imply that only the users associated to the right number 666 will be allowed to create data from the corresponding entity.

Much more complicated test may be performed, for instance some operation may required multiple access Rights in that case the list of "hasright" criteria will wrapped by a <and> criterion. On the other hand, an <or> criterion may be used if only one Right of the list is required to perform the operation:

<delete>
    <and>
        <hasright attribute="." right="666" />
        <hasright attribute="." right="667" />
    </and>
</delete>

This example, allow the deletion of this entity only to the user associated to the 666 right and the 667 right. This means that the right 666 is enough to create new data, but require the right 667 to delete a data, the right 667 does not offer any privilege by itself.

<update>
    <or>
        <hasright attribute="." right="666" />
        <hasright attribute="." right="667" />
    </or>
</update>

Here a user with only the right 667, or either the right 666, can modify a data.

Any other ISearchCriteria may be used into the access right test, the attributes and links used in this test will be those currently stored into the database when the operation is performed.

For instance:

<list>
    <or>
        <hasright attribute="." right="668" />
        <istrue attribute="public" />
    </or>
</list>

If the current user is associated to the Right number 668, he/she can list any data stored into the database, a user without this right will only be able to see the ones with the attribute "public" set on true.

Usage

The access right are used only in the web-services /data, the Java API do not check these rights. So specific implementations which may be subordinate to the entities Rights must manually include this access rights into the Mapper requests.

Some MetaDataEntity API methods may be used to work with access rights:

The method MetaDataEntity.hasRights() returns true if this entity define any access rights.
The methods MetaDataEntity.canCreate(...), canList(...), canRead(...), canDelete(...) and canUpdate(...) may be used to check if a IConnectionUserBean is allowed to perform the corresponding operation on this entity. Note that depending on the rights declaration this may require to perform a call to the database, if this call may be avoided it is.
The methods MetaDataEntity.getRightCreate(), getRightDelete(), getRightList(), getRightRead() and getRightUpdate() return the corresponding access right in as an ISearchCriteria which may be combined to another condition to perform a more complex operation. To be able to combine these condition you will have to use one of the mapper method which accept a IConnectedUserBean object to be able to set the actual current user.

Fallback rules

You do not have to declare all kind of Access right. First of all all modification related right are superseded by the value of the property "readonly" of the Entity or the Attribute.

If the Create access right is not defined then the Update Access Right is used, if this right is not defined then the Read Access right is used.
If the Delete access right is not defined then the Update Access Right is used, if this right is not defined then the Create Right is used and if this right is not defined then the Read Access right is used.
If the List access right is not defined then the Read Access Right is used (AFS version 2023.7.0+, no fallback if older versions).
If the Read access right does not have any fallback.
If the Update access right is not defined then the Create Access Right is used, if this right is not defined then the Read Access right is used.

If the is no fallback defined the the operation is authorized.

REST Resource for manipulating Entities

MetaData Entities resources

The following web-services allow to download all the MataData Eneieites definitions, including public Metadata and rights access definitions.

GET /metadata : retrieve all the entities definitions.
GET /metadata/{type} : only retrieve the entity definition corresponding to the given type.

Data access resources

The AFS resources /data/{type}/* allow to access to the entities values stored in the application. Theses resources manage the access rights to the given entities along with trigger to listeners and the throwing of OSGi Event corresponding to all the implemented operations.

All methods of theses web-service accept a parameter named "user_subtitude_to". Only usable in the query part of the URL, this parameter allow a User possessing the corresponding access right (N°3) to perform an operation in the name of another user. The value of this parameter may be a user identifier number or this identifier prefixed by the user type, for instance "user/12".

/data/{type}

This resource allow to create a new data or to read a list of data from the given entity type.

HEAD: This method allow to check the availability of this entity, and if the Entity define a modification date storage zone (e.g. with the metadata UPDATECOL), then it may be used with the conditional headers If-Modified-Since or If-Unmodified-Since. The HEAD method support all the same parameters than the GET method described below.
POST: This method allow to create a new item. The parameter of the payload are the attributes codes and their values to set in the new item. The result of this operation may be one of the following HTTP Code:
- 404: The requested entity is not currently available on the server.
- 401: The requesting user is not identifier.
- 415: The request mediatype is not suppoerted, theses resource only support JSON, XML, XSD and HTML representations.
- 500: A post traitment operation has failed the creation has been cancelled.
- 403: The modification of data is forbidden because this entity is read-only or the operation right condition is not validated.
- 400: Some mandatory attributes are missing from the parameters or some pre-creation tests have failed.
- 200: The creation operation is successful, return the created object, with its unique Identifier which must be used in next calls.
PUT: Is a synonym of the POST method for this resource.
GET: This method allow to select a list of data from the given Entity. If the Entity define a modification date storage zone, the the response Header lastModification is set to the actual most recent modification date of the selected items. This method accept the following parameters:
- attributes: List the attributes to return in the result of the query, the attributes codes must be separated with white space (or in an array for JSON payload). This parameter accept reference line of attributes. By default only the attributes declared as "listable" will be returned.
- orders: List the attribute used to order the result of the request. Each attribute code may be preceded by an exclamation mark (!) to reverse the order.
- distincts: if true only distincts results will be returned.
- pagestart: Used for pagination of results, the index if the first element of the list to return, zero is the first one. See also pagecount.
- offset: this parameter is a synonym of pagestart.
- pagecount: Used for pagination of results, the maximal number of elements to return, use -1 for unlimited. See also pagestart.
- limit: Used for pagination of results, the maximal number of elements to return, use -1 for unlimited. See also pagestart.
- criteria: Define the selection condition to get the list of items, see Search Criteria for details.
DELETE: This method allow to delete a list of items based on a given conditional selection. This method access the following parameters:
- criteria: Define the selection condition to get the list of items to delete.
- harddelete: if set to true, the deletion operation will ignore the soft-deletion facility declared by the Entity.

/data/{type}/{id}

This resource allow to access to a explicitly set of items, identified by their internal ID. Basically one item is acceded at a time but you may access to multiple items at the same time by listing the id separated by a plus sign (e.g. a GET method call to /data/user/1+2+3 will return the three users with Id 1, 2 and 3).

Instead of using internal identifier (ID) to select the item to access, if the corresponding entity define a "code" attribute, you may use these code values. You can still pass multiples code at the came type using the plus sign.

HEAD: This method allow to check the availability of the given items entity, and if some of them exist and their Entity define a modification date storage zone, then it may be used with the conditional headers If-Modified-Since or If-Unmodified-Since. The HEAD method support all the same parameters than the GET method described below.
GET: This method allow to list the content of the designated items.
PUT: This method allow to modify an existing set of items.
DELETE: This method
POST: is a synonym of the PUT Method for this resource.

/data/{type}/{id}/{link}

/data/{type}/{id}/{link}/{lid}

/data/{type}/{id}/{ext}

Some other extension may be added to specifix entities, just like the "Binary file attachment" service which define for the entities that declared it a resource /data/{type}/{id}/bin allowing to manage one or more files attached to the given item.

Metadata Entities - ARCAD-Software/AFS GitHub Wiki

Entity definition

Entities properties

Entity Attributes

Elementary types

The Associations (Links) of entities

Search Criteria representation

Composed Criteria

Constants criteria

Attributes value testing

Links testing

Specific criteria

Entity manipulation API

Example of a simple entity

Entities right management

REST Resource for manipulating Entities

MetaData Entities resources

Data access resources

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️