Model Module

The Model Module provides a dedicated API for the XWiki Data Model. The source code is published on GitHub at xwiki-platform-model.

XWiki Data Model

The XWiki Data Model is composed of entities:

  • WIKIS made of
  • SPACES made of
  • PAGES which can contain ATTACHMENTS, OBJECTS or CLASS definitions
  • an OBJECT contains OBJECT PROPERTIES
  • a CLASS contains CLASS PROPERTIES

Entity Resolver API

EntityReference

An EntityReference is a reference to an entity: wiki, space, page, attachment etc. Regarding the parent, an entity reference:

  • can be relative or absolute, which means that all its parent references are defined up to the wiki reference
  • can have another entity reference as parent, just like in the case of wiki pages for which the parent is a space reference

Each entity reference type has a dedicated API:

  • WikiReference - a reference to a wiki name. This reference does not have a parent.
  • SpaceReference - a reference to a space name.
  • DocumentReference - a reference to a document name i.e. the wiki, space and page names.

    The string syntax is: wiki:space.page. Some possible string representations are:

    - Wiki:Space.Page
    - a relative reference when the wiki is not specified: Space.Page
    - a relative reference when the wiki and space are not specified: Page
    - a page containing a dot in the name needs to be escaped using the "\" character: Dot\.Page

  • AttachmentReference - a reference to an attachment which is composed of a document reference (because an attachment is always attached to a document) and a file name.

    The string syntax is: Wiki:Space.Page@Filename. Some possible string representations are:

    - Wiki:Space.Page@Filename
    - a relative reference when the wiki is not specified: Space.Page@Filename
    - a relative reference when the wiki and space are not specified: Page@Filename
    - a relative reference when the wiki, space and page are not specified: Filename
    - an attachment containing the "@" character in the name needs to be escaped using "\": File\@name

  • ObjectReference - a reference to an object attached to a document: class name and index, document, space and wiki.

    The string syntax is: Wiki:Space.Page^Object. Some possible string representations are:

    - Wiki:Space.Page^Object
    - a relative reference when the wiki is not specified: Space.Page^Object
    - a relative reference when the wiki and space are not specified: Page^Object
    - a relative reference when the wiki, space and page are not specified: Object
    - an object containing the "^" character in the name needs to be escaped using "\": Ob\^ject

  • ObjectPropertyReference - a reference (the value of the property) to an object property in a document.

    The string syntax is: Wiki:Space.Page^Object.Property. Some possible string representations are:

    - Wiki:Space.Page^Object.Property
    - a relative reference when the wiki is not specified: Space.Page^Object.Propertyt
    - a relative reference when the wiki and space are not specified: Page^Object.Property
    - a relative reference when the wiki, space and page are not specified: Object.Property
    - a relative reference when the wiki, space, page and object are not specified: Property
    - an object containing a dot in the name needs to be escaped using "\": Pro\.perty

  • ClassPropertyReference - a reference (description) to a class property in a document.

Examples

To create an  entity reference, you could use the below code snippets:

1. Create a Document reference pointing to the "wiki:space.page" document: DocumentReference reference = new DocumentReference("wiki", "space", "page");

2. Create a reference which is relative to a space: EntityReference reference = new EntityReference("space", EntityType.SPACE);

3. Create a Document reference by defining parent references

This snippet is equivalent to the first one: DocumentReference reference = new DocumentReference("wiki", "space", "page");

EntityReference reference = new EntityReference("page", EntityType.DOCUMENT,
    new EntityReference("space", EntityType.SPACE,
        new EntityReference("wiki", EntityType.WIKI)));

EntityReferenceResolver

An EntityReferenceResolver resolves an entity reference defined in a given representation into a validated "EntityReference" object having valid values and a valid hierarchy. For instance, a Document reference must have a Space reference as parent and reference values must not be null.

There are 2 types of Resolvers:

  • Resolvers that take as input a String representing a reference and convert it to an "EntityReference" which is usually absolute.
  • Resolvers that take as input an "EntityReference" and convert it to another "EntityReference" which is also usually absolute. You might need these Resolvers in order to convert a relative Reference into an absolute one.

For both the above resolvers, there are various categories:

The default Resolver

The default Resolver takes a String or an "EntityReference" as input and it is used when there are several entity parts missing from the input. The default values can be configured by editing the "WEB-INF/xwiki.properties" file like for example:


model.reference.default.wiki = mywiki (defaults to "xwiki")
model.reference.default.space = myspace (defaults to "Main")
model.reference.default.document = mypage (defaults to "WebHome")
model.reference.default.attachment = myfilename (defaults to "filename")
model.reference.default.object = myobject (defaults to "object")
model.reference.default.object_property = myproperty (defaults to "property")

The current Resolver

The current Resolver takes a String or an "EntityReference" as input and uses the current entity reference to fill in the missing entity parts from the input. If no current entity part is found, the default part values are used.

The currentmixed Resolver

The currentmixed Resolver takes a String or an "EntityReference" as input. The difference is that in case the passed reference doesn't have a page name specified or is empty, the value used is the default page name instead of the page name of the current document reference.

The relative Resolver

The relative Resolver only takes a String as input and transforms the representation into an "EntityReference" instance, but it doesn't resolve the missing entity parts.

The explicit Resolver

The explicit Resolver takes a String or an "EntityReference" as input and is used exclusively to resolve missing entity parts. The Resolver must be called with an "EntityReference" parameter.

EntityReferenceSerializer

The EntityReferenceSerializer generates a different representation for an entity reference, like for instance a String representation.

There are various Serializers and they all take an "EntityReference" as input and generate a String representation:

  • default - prints all parts of the passed "EntityReference".
  • compact - doesn't print the parts that match the current entity in the execution context or the passed entity reference, if any. An important detail is that the final part (like the document page for a Document Reference or the attachment file name for an Attachment Reference) is always kept.
  • compactwiki - generates an entity reference string that doesn't contain the wiki reference part if the passed reference matches the current wiki. The Space and Page references are always printed.

Reference Set

You can use the EntityReferenceSet class to create a matcher combining included and excluded references. For instance, to match all references in the "wiki:space" space except for the "wiki:space.document" document, use the below snippet:

EntityReferenceSet set = new EntityReferenceSet();

set.includes(new SpaceReference("space", new WikiReference("wiki")));
set.excludes(new DocumentReference("wiki", "space", "document"));

Reference Tree

The EntityReferenceTree class can be used to create a navigable tree of entity references, like for example:

EntityReferenceTree tree = new EntityReferenceTree(new DocumentReference("wiki", "space", "page"), new DocumentReference("wiki", "space", "page2"));

API Examples

Generate a "DocumentReference" using a current Resolver which fills the wiki and space parts with the current wiki and space

@Inject
@Named("current")
private DocumentReferenceResolver<String> resolver;
DocumentReference reference = resolver.resolve("Page");

Generate a "DocumentReference" using a default Resolver which fills the wiki part with the default wiki name ("xwiki")

@Inject
private DocumentReferenceResolver<String> resolver;
DocumentReference reference = resolver.resolve("Space.Page");

Generate a "DocumentReference" using a default Resolver which fills the space part with the default space name ("Main") and forces the wiki part to use a fixed value if not defined:

@Inject
private DocumentReferenceResolver<String> resolver;
DocumentReference reference = resolver.resolve("Page", new WikiReference("mynewwiki"));

Serialize a Document Reference into a String

@Inject
private EntityReferenceSerializer<String> serializer;
String serializer = serializer.serialize(reference);

Lookup the "DocumentReference" using a current Resolver

DocumentReferenceResolver<String> stringResolver = componentManager.getInstance(DocumentReferenceResolver.TYPE_STRING, "current");
DocumentReferenceResolver<EntityReference> referenceResolver = componentManager.getInstance(DocumentReferenceResolver.TYPE_REFERENCE, "current");

Resolve the "Sandbox.TestPage1" page reference and generate its string representation by filling the missing wiki with the current wiki

DocumentReferenceResolver<String> stringResolver = componentManager.getInstance(DocumentReferenceResolver.TYPE_STRING, "current");
EntityReferenceSerializer<String> stringSerializer = componentManager.getInstance(EntityReferenceSerializer.class);
String sandboxName = "Sandbox.TestPage1";

DocumentReference sandboxRef = stringResolver.resolve(sandboxName);

// display the page name (TestPage1)
sandboxRef.getName();

// display the space name (Sandbox)
sandboxRef.getParent().getName();

// display the current wiki
sandboxRef.getParent().getParent().getName();

// serialize the reference:
String sandbox = stringSerializer.serialize(sandboxRef); // will give <current_wiki>:Sandbox.TestPage1

Script Service API Examples

Generate a string representation for the parent reference relative to the current document

{{velocity}}
#set ($parentReference = $services.model.resolveDocument($doc.parent, 'currentmixed', $doc.documentReference))
$services.model.serialize($parentReference)
{{/velocity}}

Create a Document Reference for the "Main.WebHome" page on the main wiki

{{velocity}}
#set ($mainWikiDocumentReference = $services.model.createDocumentReference($xcontext.mainWikiName, 'Main', 'WebHome'))
{{/velocity}}

Create a Document Reference for the "Main.WebHome" page on the current wiki using the current resolver

{{velocity}}
#set ($mainDocumentReference = $services.model.createDocumentReference('', 'Main', 'WebHome'))
{{/velocity}}

Create an Entity Reference for a document with a wiki parent specified but without a space reference

{{velocity}}
#set ($ref = $services.model.createEntityReference('page', 'document', $services.model.createEntityReference('wiki', 'wiki')))
{{/velocity}}

Create an Entity Reference tree from a list of Entity References

{{velocity}}
#set ($ref = $services.model.toTree($references))
{{/velocity}}

 

Search this space