org.nuiton.wikitty.Package.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of wikitty-api Show documentation
Public wikitty API
The newest version!

Wikitty API documentation

Extensions version management

The extension version number have to be managed by the developer who writes or
modify the extension.

When we modify an extension in a model, a developer have to remember to  update
the version tag/value.

Objects deletion management

The objects deleted are only marked as deleted, like that it will be possible to
restore a deleted object in future implementations.

The deleted objects are not indexed anymore (and so do not appear in search
results).

If we try to get a deleted object by its id, null is returned.

We cannot save a deleted object until we do a undelete on it.

Wikitties attributes

It is possible to define several things for a wikitty field :


    its type (String)
    its name (String)
    its cardinality ([1-n])
    if it is unique (unique), for the lists it will be reprensted by a Set, for
        not-list objects it means that two objects cannot have the same value for
        this field (constraint not implemented for now).
    
    if it has to be not null, there is no mean, in the modeler to indicate it,
        and so it is not possible to generate it.
    
    Tag/values (tag=value). It is possible to create as many tag/values as we
        want. You can then get them by FieldType.getTagValue(tagName). This can be
        useful to put a tag 'editor' used by UI and that allows to put a specific
        editor for a field (e.g. a html editor for a String field)
    


PropertyChangeListener

The field modification listeners management is diretly done by the wikitty
object. The name of the field is the concatenation of the extension name and the
field name ([extName].[fieldName]).

Search API

General points

The search are made by example (a model dto), or from a search 'Criteria' object.

This criteria contains restrictions that will be turned into searhc request.

The criteria can be built from the utility class 'Search' that allows to express,
via instructions, all the restrictions.

The Search operations return a reference to an object of the same type allowing
to continue expressing other criteria.

This allows to write quickly and easily search expressions with the Search API's
help (and auto-completion will help even more).

The Search operations names are really short and syntaxically close to bash
conditional expressions...

List of criteria operations
We will find : 
     eq : to express equality
     neq : to express difference (not equals)
     le, lt : respectively for inclusive and exclusive inferiority operations
        (less than, less or equals)
     ge, gt : respectively for inclusive and exclusive superiority operations
        (greater than, greater or equals)
     sw : to express an expression beginning (start with)
     ew : to express an expression ending (end with)
     in : to express a list of possible values


Disjunction operation, disjunction group
By default, each restrictions express by the above expressions are added to a
list of conjunctions (logical AND).

It is possible to express disjunctions (logical OR) using the or operation.

The restriction following the or is then in disjunction with the one preceding
it.

If other restrictions are added after that, they are attached to the previous
conjunction.

To express a group of disjunction, we can call the or operation between each
restriction or call the group operation with the 'OR' type.

In this last case, you will need to close the groupe by calling the end operation.

Associative search
It is possible to express associative search, i.e. search for which some criteria
are based on objects linked by a reference (link or foreign key notion).

Then, the associated (fieldName) operation allows to
Il est possible d'exprimer des recherches associatives, c'est à dire des recherches pour lesquelles certains critères portent sur un objet lié par une référence (notion de lien, ou de clé étrangère).

Ainsi, l'opération associated( fieldName ) permet de faire porter les critères suivant cette opération sur les objets lié via ce champ.

Le résultat sera une conjonction (ET) entre les critères exprimés avant l'opération associated sur l'objet 'principal' (il peut ne pas y en avoir), et dont la ou les références associée répondent aux critères exprimés après le associated.

Tout cela est beaucoup plus clair par l'exemple ;-)


I want to find all paints between 15 and 25 euros in the Hardware section.

This search can be expressed ina more concrete way using API via :

"I search all products wich price is between 15 and 25 euros, which name starts
by 'Paint', and which associated section, using the 'section' field, have the
name 'Hardware'".

It is built using the following operations :

    RestrictionDto dto = Search.query()
        .bw( "Product.selling_price", "15", "25")
        .sw( "Produit.article_name", "Paint")
        .associated( "Product.section" )
            .eq( "Section.name", "Hardware" )
        .criteria();
 


Data migration

When the list of wikitty extensions is modified, either:

    we deleted an extension, the data stays in the wikitty
    we added an extension, nothing is done but we can add data for the new
        fields
    we modified an extension
    
deleted an extension field : the data stays but are no more
        accessible
    added a field to the extension : nothing is done but we can add data
        for the new field
    modified a field type:
        
            API knows how to convert it, nothing to do (e.g. int->String)
            The type has been deeply modified (e.g. String->List<int<):
                you have to implement an extension migration sub-class
                (WikittyExtensionMigration) and save it so that it is used when
                necessary.
        
    


An object is converted when it is loaded in its BusinessEntity, but is is not
    automatically save, it is saved only if a store is called on the client side.


It is also possible to force the migration searching all the objects with the
modified extension, load them in WikittyDtos and save them.
Wikitty w = new Wikitty();
w.addExtension(myModifiedExtension);
WikittyDto dto = new WikittyDto(w);
PagedResult<WikittyDto> result = proxy.findAllByExample(dto, 0, Proxy.ALL_ELEMENTS);
proxy.store(result.getAll());


Import Wikitties

When importing XML file, if an object has a version nmber, then if in the
database there is no object or if the object has a version number less or equal
than the imported version number, the xml file data overwrite the database data.

If the database version number is greater than the imported version number, the
imported object is rejected and an exception is thrown.

If the imported object had no version number, in all cases, it overwrite  the
database data and the object version number is incremented if it was present in
database.

Modifications to do on implementation :

    During xml file reading and loading into wikitty object, if there is no
        version number in xml flux, the version number is null instead of
        defaultversion.
    Take into account that during wikitty save, the version number can be
        null, do the appropriate treatment


If an object in database was deleted and we try to import it, we throw an
exception.

TODO

while generating BusinessEntity, if 2 extensions have the same method,
    suffix the next ones with xxxxxxForExtensionName
Think about object search problem if its extensions have been modified.
    If you do a search by example, we add the extension list in the request, the
    new BusinessEntity has more extensions, we do not find the old objects. If
    we do a search by criteria/example, the criterie field cannot exist in the
    index and so the object is not returned in results even if we put '*' as
    field value.