org.xwiki.platform:xwiki-platform-modelXWiki Platform - Modeljar15.0

XWiki Model (Wiki, Space, Document, etc)

The XWiki Model is made of Entities, such as: * A Wiki contains Spaces * A Space contains Documents * A Document contains Attachments and Objects (a.k.a XObjects), and can also contain one Class definition (XClass) * {{info}}since 10.6{{/info}} A Page is another way to represent Space/Document hierarchy * An Object contains Object Properties * A Class contain Class Properties == Entity Reference API == There are 3 concepts to understand: * The notion of **{{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/EntityReference.java"}}EntityReference{{/scm}}** (or Reference for short). ** A Reference points to an Entity from the Model (wiki, space, document, object, etc). ** A Reference can have a parent Reference (e.g. a Document Reference's parent is a Space Reference) ** {{version since="16.4.7,16.10.2"}}A Reference can have a Parent Type Reference which is used to define how to resolve relative references (e.g. a relative Space having a Wiki parent type won't be resolved the same than a relative Space having a Space parent type){{/version}} ** A Reference can be absolute (i.e. all its parent references are defined till the wiki Reference) or relative. ** To make it easy to construct References, a typed API exists. For example {{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/WikiReference.java"}}WikiReference{{/scm}}, {{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/SpaceReference.java"}}SpaceReference{{/scm}}, {{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/DocumentReference.java"}}DocumentReference{{/scm}}, {{scm path="master/xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/AttachmentReference.java"}}AttachmentReference{{/scm}}, and {{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference"}}more{{/scm}}. * The notion of **{{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/EntityReferenceResolver.java"}}EntityReferenceResolver{{/scm}}** (Resolver for short). The goal of a Resolver is to take some input and convert it to an EntityReference instance. An example is an input defined as a String, such as ##wiki:space.document##. * The notion of **{{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/reference/EntityReferenceResolver.java"}}EntityReferenceSerializer{{/scm}}** (Serializer for short). The goal of a Serializer is to convert an EntityReference instance into a given representation. For example a Serializer could convert a Reference into its string representation, e.g. ##xwiki:space.document##. === Constructing an Entity Reference === Examples: {{code language="java"}} // A Document Reference pointing to the wiki:space.document document DocumentReference reference = new DocumentReference("wiki", "space", "document"); // A Page Reference pointing to the wiki:page1/page2 page PageReference reference = new PageReference("wiki", "page1", "page2"); // A Document Reference pointing to the space.document document in an undefined wiki (i.e. without the wiki part) LocalDocumentReference reference = new LocalDocumentReference("space", "document"); // A relative reference, specifying only a space EntityReference reference = new EntityReference("space", EntityType.SPACE); // A document reference, specified using the generic EntityReference API, defining parent references // The constructed reference is equivalent to: new DocumentReference("wiki", "space", "document"). EntityReference reference = new EntityReference("document", EntityType.DOCUMENT, new EntityReference("space", EntityType.SPACE, new EntityReference("wiki", EntityType.WIKI))); {{/code}} === Resolving a Reference === ==== From String and EntityReference ==== There are various types of Resolvers, the 2 most important are: * Resolvers which take a String representing a Reference as input and convert it to an EntityReference (usually Absolute) * Resolvers which take an EntityReference as input and convert it to a EntityReference (usually Absolute). These Resolvers are often used to convert a relative Reference into an absolute Reference. For both types of Resolvers, there are various Resolvers that exist: * ##default## Resolver(String or EntityReference input): When some reference parts are missing from the input, default values are used (see the configuration example below for default values). These default values can be configured (using the Configuration Module) to use specific default values for missing Entity parts. This is achieved by editing the ##xwiki.properties## file. For example:((( {{code language="none"}} model.reference.default.wiki = mywiki (defaults to "xwiki") model.reference.default.space = myspace (defaults to "Main") model.reference.default.document = mydocument (defaults to "WebHome") model.reference.default.page = mypage (defaults to "Main") 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") {{/code}} ))) * ##current## Resolver(String or EntityReference input): Uses the current Entity Reference to fill missing parts from the input (i.e. current wiki, current space, current page, etc). If there's no current entity part then uses the default part values. * ##currentmixed## Resolver(String or EntityReference input): Same as ##current## but if the passed reference doesn't have a document name specified (or if it's empty) the value used is the default document name (instead of the document name of the current document's reference) * ##relative## Resolver (String input only): Doesn't generate absolute references; simply transforms a String representation into an EntityReference instance without resolving any missing parts (space, wiki, page, etc). * ##withparameters## Resolver (String input only): same as the ##default## one but also support the standar entity reference parameters syntax for all types and not only for PAGE based reference The API to call a Resolver is: {{code language="java"}} public interface EntityReferenceResolver<T> { /** * @param entityReferenceRepresentation the representation of an entity reference (eg as a String) * @param type the type of the Entity (Document, Space, Attachment, Wiki, etc) to resolve out of the representation, * since 14.8 it's possible to pass null if the resolver should extract the type from the representation * itself * @param parameters optional parameters. Their meaning depends on the resolver implementation * @return the valid resolved reference as an Object */ EntityReference resolve(T entityReferenceRepresentation, EntityType type, Object... parameters); } {{/code}} Note that all the Resolvers listed above will honor passing an EntityReference as ##parameters##. If one is passed then it'll be used to resolve missing entity parts. In addition to the Resolved listed above there's a special one: * ##explicit## Resolver (String or EntityReference input): Must be called with an EntityReference parameter and this reference is used exclusively to resolve missing entity parts. Some "typed" resolvers are also provided as helpers: * ##org.xwiki.model.reference.DocumentReferenceResolver## (since 2.2M1) * ##org.xwiki.model.reference.AttachmentReferenceResolver## (since 2.2M1) * ##org.xwiki.model.reference.ObjectReferenceResolver## (since 2.3M1) * ##org.xwiki.model.reference.ObjectPropertyReferenceResolver## (since 2.3M1) * ##org.xwiki.model.reference.SpaceReferenceResolver## (since 7.2M1). * ##org.xwiki.model.reference.PageReferenceResolver## (since 10.6RC1) * ##org.xwiki.model.reference.PageAttachmentReferenceResolver## (since 10.6RC1) * ##org.xwiki.model.reference.PageObjectReferenceResolver## (since 10.6RC1) * ##org.xwiki.model.reference.PageObjectPropertyReferenceResolver## (since 10.6RC1) ==== Other types ==== It's also possible to resolve EntityReference from different types: * from an [[##org.xwiki.rendering.listener.reference.ResourceReference##>>doc:rendering:Main.Extending.WebHome||anchor="HAddinganewLinkType"]]: this resolver allows to resolve a resource reference as expressed in a XWiki 2.1 Syntax to an actual EntityReference which can be used in all APIs. {{version since="16.4.7,16.10.2"}}we also provide a relative resolver allowing to resolve a resource reference to a relative EntityReference{{/version}} === Serializing a Reference === There are various Serializers that all take an EntityReference as input and generate a String representation of it: * ##default##: Prints all parts of the passed EntityReference. * ##compact##: Don't print parts that are the same as either the current entity in the Execution Context or as the passed entity reference (if any). Note that the terminal part is always kept (eg the document's name for a document reference or the attachment's filename for an attachment reference). * ##compactwiki##: Don't print the wiki reference part if the passed reference matches the current wiki or as the wiki of the passed entity reference (if any). The space reference and document references are always printed. * ##local##: Never print the wiki reference part. * ##uid##: Fast unique String reference. It's not meant to be parsed but to get a unique String for a given reference as fast as possible. It's mostly used as cache and database identifiers. Since 8.3RC1 it also support serializing the Locale part of a reference. * ##withparameters##: same as the ##default## one but also serialize the parameters for all types and not only for PAGE based reference * ##withtype##: same as the ##default## one but prefix the reference with the entity type * ##withtype/withparameters##: a combination of both ##withtype## and ##withparameters## specifications The API to call a Serializer is: {{code language="java"}} public interface EntityReferenceSerializer<T> { /** * Serialize an entity reference into a new representation of type <T>. * * @param reference the reference to serialize * @param parameters optional parameters. Their meaning depends on the serializer implementation * @return the new representation (eg as a String) */ T serialize(EntityReference reference, Object... parameters); } {{/code}} === Reference Set === {{info}}Since XWiki 5.2{{/info}} ##org.xwiki.model.reference.EntityReferenceSet## can be used to create a matcher combining included and excluded references. The following example matches all references in the **##wiki:space##** space except the **##wiki:space.document##** document: {{code language="java"}} EntityReferenceSet set = new EntityReferenceSet(); set.includes(new SpaceReference("space", new WikiReference("wiki"))); set.excludes(new DocumentReference("wiki", "space", "document")); {{/code}} === Reference tree === {{info}}Since XWiki 5.4{{/info}} ##org.xwiki.model.reference.EntityReferenceTree## can be used to create a navigable tree of entity references. {{code language="java"}} EntityReferenceTree tree = new EntityReferenceTree(new DocumentReference("wiki", "space", "document"), new DocumentReference("wiki", "space", "document2")); {{/code}} === The various References types === ==== Page References ==== {{info}}Since 10.6{{/info}} General string syntax: {{code language="none"}}wiki:page1/page2{{/code}} Note that you don't specify ##WebHome## for nested pages, compared to Entity Reference or Document Reference. Examples of string representations: * ##Wiki:Page1/Page2## * ##Page1/Page2## (wiki not specified, it's a relative reference) * ##My\/Page## (page with a slash in the name which needs to be escaped as otherwise "My" would be considered as a parent page name) * ##..## (parent page) * ##./ChildPage## (page under current page) * ##Page;en_US## (page with locale en_US) * ##Page;key=value;en_US## (page with lcoale en_US and custom parametere "key" with value "value") API examples: * Generate a PageReference using a "current" Resolver, filling wiki with the current wiki:((( {{code language="java"}} @Inject @Named("current") private PageReferenceResolver<String> resolver; ... PageReference reference = resolver.resolve("Page"); {{/code}} ))) * Serialize a Page Reference into a String:((( {{code language="java"}} @Inject private EntityReferenceSerializer<String> serializer; ... String serializer = serializer.serialize(reference); {{/code}} ))) * Lookup the "current" Page Reference resolver (in case you can't have it injected):((( {{code language="java"}} PageReferenceResolver<String> stringResolver = componentManager.getInstance(PageReferenceResolver.TYPE_STRING, "current"); PageReferenceResolver<EntityReference> referenceResolver = componentManager.getInstance(PageReferenceResolver.TYPE_REFERENCE, "current"); {{/code}} ))) * Resolve the sandbox page reference and generate its string representation filling the missing wiki with the current wiki:((( {{code language="java"}} PageReferenceResolver<String> stringResolver = componentManager.getInstance(PageReferenceResolver.TYPE_STRING, "current"); EntityReferenceSerializer<String> stringSerializer = componentManager.getInstance(EntityReferenceSerializer.class); String sandboxName = "Sandbox.TestDocument1"; PageReference sandboxRef = stringResolver.resolve(sandboxName); // sandboxRef.getName() will give the page name TestDocument1 // sandboxRef.getParent().getName() will give the parent page name Sandbox // sandboxRef.getParent().getParent().getName() will give the current wiki // serialize the reference: String sandbox = stringSerializer.serialize(sandboxRef) // will give <current_wiki>:Sandbox.TestDocument1 {{/code}} ))) ==== Local Page References ==== {{info}}Since 10.6{{/info}} Same as PageReference but without the wiki part. There is no dedicated resolver, it's mostly used as a helper to create a local page reference. {{code language="java"}} LocalPageReference reference = new LocalPageReference("page1", "page2"); {{/code}} ==== Page Attachment References ==== {{info}}Since 10.6{{/info}} General string syntax: {{code language="none"}}Wiki:Page1/Page2/filename{{/code}} Examples of string representations: * ##Wiki:Page1/Page2/filename## * ##Page1/Page2/filename## (wiki not specified, it's a relative reference) * ##filename## (wiki and page not defined, it's a relative reference) * ##file\/name## (attachment name with a slash in the name which needs to be escaped as otherwise "file" would be considered as a page name) ==== Page Object References ==== {{info}}Since 10.6{{/info}} General string syntax: {{code language="none"}}Wiki:Page1/Page2/Object{{/code}} Examples of string representations: * ##Wiki:Page1/Page2/Object## * ##Page1/Page2/Object## (wiki not specified, it's a relative reference) * ##Object## (wiki, page not defined, it's a relative reference) * ##Ob\/ject## (object name with a slash in the name which needs to be escaped as otherwise "Ob" would be considered as a page name) ==== Page Object Property References ==== {{info}}Since 10.6{{/info}} General string Syntax: {{code language="none"}}Wiki:Page1/Page2/Object/Property{{/code}} Examples of string representations: * ##Wiki:Page1/Page2/Object/Property## * ##Page1/Page2/Object/Property## (wiki not specified, it's a relative reference) * ##Object/Property## (wiki and page not defined, it's a relative reference) * ##Property## (wiki, page and object not defined, it's a relative reference) * ##Pro\/perty## (object name with a slash in the name which needs to be escaped as otherwise "Pro" would be considered as a page name) ==== Page Class Property References ==== {{info}}Since 10.6{{/info}} General string Syntax: {{code language="none"}}Wiki:Page1/Page2/ClassProperty{{/code}} ==== Document References ==== General string syntax: {{code language="none"}}wiki:space.document{{/code}} Examples of string representations: * ##Wiki:Space.Document## * ##Space.Document## (wiki not specified, it's a relative reference) * ##Document## (wiki and space not specified, it's a relative reference) * ##My\.Document## (document with a dot in the name which needs to be escaped as otherwise "My" would be considered as a space name) * ##Document;en_US## (page with locale en_US) * ##Document;key=value;en_US## (page with locale en_US and custom parametere "key" with value "value") API examples: * Generate a DocumentReference using a "current" Resolver, filling wiki and space parts with the current wiki and space:((( {{code language="java"}} @Inject @Named("current") private DocumentReferenceResolver<String> resolver; ... DocumentReference reference = resolver.resolve("Document"); {{/code}} ))) * Generate a DocumentReference using a "default" Resolver, filling the wiki part with the default wiki name ("xwiki" by default but can be configured):((( {{code language="java"}} @Inject private DocumentReferenceResolver<String> resolver; ... DocumentReference reference = resolver.resolve("Space.Document"); {{/code}} ))) * Generate a DocumentReference using a "default" Resolver, filling the space part with the default space name ("Main" by default but can be configured), and forcing the wiki part to use a fixed value if not defined:((( {{code language="java"}} @Inject private DocumentReferenceResolver<String> resolver; ... DocumentReference reference = resolver.resolve("Document", new WikiReference("mywiki")); {{/code}} ))) * Serialize a Document Reference into a String:((( {{code language="java"}} @Inject private EntityReferenceSerializer<String> serializer; ... String serializer = serializer.serialize(reference); {{/code}} ))) * Lookup the "current" Document Reference resolver (in case you can't have it injected):((( Starting with XWiki 4.0: {{code language="java"}} DocumentReferenceResolver<String> stringResolver = componentManager.getInstance(DocumentReferenceResolver.TYPE_STRING, "current"); DocumentReferenceResolver<EntityReference> referenceResolver = componentManager.getInstance(DocumentReferenceResolver.TYPE_REFERENCE, "current"); {{/code}} Before XWiki 4.0: {{code language="java"}} DocumentReferenceResolver<String> stringResolver = componentManager.getInstance(DocumentReferenceResolver.class, "current"); DocumentReferenceResolver<EntityReference> referenceResolver = componentManager.getInstance(DocumentReferenceResolver.class, "current/reference"); {{/code}} ))) * Resolve the sandbox document reference and generate its string representation filling the missing wiki with the current wiki (starting with 4.0):((( {{code language="java"}} DocumentReferenceResolver<String> stringResolver = componentManager.getInstance(DocumentReferenceResolver.TYPE_STRING, "current"); EntityReferenceSerializer<String> stringSerializer = componentManager.getInstance(EntityReferenceSerializer.class); String sandboxName = "Sandbox.TestDocument1"; DocumentReference sandboxRef = stringResolver.resolve(sandboxName); // sandboxRef.getName() will give the document name TestDocument1 // sandboxRef.getParent().getName() will give the space Sandbox // sandboxRef.getParent().getParent().getName() will give the current wiki // serialize the reference: String sandbox = stringSerializer.serialize(sandboxRef) // will give <current_wiki>:Sandbox.TestDocument1 {{/code}} ))) {{version since="14.8RC1"}} A DocumentVersionReference is now present in the model: this is a special kind of DocumentReference which sets a parameter named version with the given version, and allow to retrieve it through the API. {{code language="java"}} DocumentReference reference = resolver.resolve("Space.Document"); DocumentVersionReference versionRef = new DocumentVersionReference(reference, "1.4"); String version = versionRef.getVersion(); {{/code}} {{/version}} ==== Local Document References ==== Same as DocumentReference but without the wiki part. There is no dedicated resolver, its mostly used as a helper to create a local document reference (often used for XWiki classes for example). {{code language="java"}} LocalDocumentReference reference = new LocalDocumentReference("Space", "document"); {{/code}} ==== Attachment References ==== General string syntax: {{code language="none"}}Wiki:Space.Document@Filename{{/code}} Examples of string representations: * ##Wiki:Space.Document@Filename## * ##Space.Pocument@Filename## (wiki not specified, it's a relative reference) * ##Document@Filename## (wiki and space not specified, it's a relative reference) * ##Filename## (wiki, space, document not defined, it's a relative reference) * ##File\@name## (attachment name with a '@' symbol in the name which needs to be escaped as otherwise "File" would be considered as a document name) ==== Object References ==== General string syntax: {{code language="none"}}Wiki:Space.Document^Object{{/code}} Examples of string representations: * ##Wiki:Space.Document^Object## * ##Space.Document^Object## (wiki not specified, it's a relative reference) * ##Document^Object## (wiki and space not specified, it's a relative reference) * ##Object## (wiki, space, document not defined, it's a relative reference) * ##Ob\^ject## (object name with a '^' symbol in the name which needs to be escaped as otherwise "Ob" would be considered as a document name) In XWiki the ##Object## name is of the form <class reference>[number] with the number being optional, for example: * Wiki:Space.Document^MySpace.MyClass[0] * Wiki:Space.Document^MySpace.MyClass ==== Object Property References ==== General string Syntax: {{code language="none"}}Wiki:Space.Document^Object.Property{{/code}} Examples of string representations: * ##Wiki:Space.Document^Object.Property## * ##Space.Document^Object.Property## (wiki not specified, it's a relative reference) * ##Document^Object.Property## (wiki and space not specified, it's a relative reference) * ##Object.Property## (wiki, space, document not defined, it's a relative reference) * ##Property## (wiki, space, document and object not defined, it's a relative reference) * ##Pro\.perty## (object name with a dot in the name which needs to be escaped as otherwise "Pro" would be considered as an object name) ==== Class Property References ==== General string Syntax: {{code language="none"}}Wiki:Space.Document^ClassProperty{{/code}} == Script Service API == Full API is available {{scm path="xwiki-platform-core/xwiki-platform-model/src/main/java/org/xwiki/model/script/ModelScriptService.java"}}here{{/scm}}. Examples: * Create a Document Reference:((( {{code language="velocity"}} #set ($reference = $services.model.createDocumentReference("wiki", ["space"], "document")) {{/code}} Note that prior to XWiki 7.2, the API was: {{code language="velocity"}} #set ($reference = $services.model.createDocumentReference("wiki", "space", "document")) {{/code}} ))) * Generate a string representation for the parent reference relative to the current document (example in Velocity):((( {{code language="velocity"}} #set ($parentReference = $services.model.resolveDocument($doc.parent, 'currentmixed', $doc.documentReference)) $services.model.serialize($parentReference) {{/code}} ))) * Create a document reference for the ##Space1.Space2.WebHome## document on the main wiki:((( {{code language="velocity"}} #set ($workspaceManagerMainDocumentReference = $services.model.createDocumentReference($xcontext.mainWikiName, ['Space1', 'Space2'], 'WebHome')) {{/code}} ))) * Create a document reference for the ##Space1.Space2.WebHome## document on the current wiki (any param can be an empty string and in this case it'll be resolved using the ##current## resolver):((( {{code language="velocity"}} #set ($workspaceManagerMainDocumentReference = $services.model.createDocumentReference('', ['Space1', 'Space2'], 'WebHome')) {{/code}} ))) * Create an Entity Reference for a document with a wiki parent specified but not space reference specified:((( {{code language="velocity"}} #set ($ref = $services.model.createEntityReference('document', 'document', $services.model.createEntityReference('wiki', 'wiki'))) {{/code}} ))) * {{info}}Since XWiki 5.4{{/info}} Create an Entity Reference tree from a list of Entity References:((( {{code language="velocity"}} #set ($ref = $services.model.toTree($references)) {{/code}} ))) * Create a reference to a sibling of the current document:((( {{code language="velocity"}} // Solution 1 (simplest and best): #set ($ref = $services.model.resolveDocument('siblingdocument', $doc.documentReference)) // Solution 2: #set ($ref = $services.model.createEntityReference('siblingdocument', 'DOCUMENT', $doc.documentReference.parent)) {{/code}} ))) * Resolve the current page's Space home page (without hardcoding ##WebHome## which is a bad practice):((( {{code language="velocity"}} $services.model.resolveDocument('', 'default', $doc.documentReference.lastSpaceReference) {{/code}} Some explanations: * The empty name means we're letting the resolver figure it out * The ##default## string means we want to use the Default Resolver (if not specified, it's the current resolver that would be used, hence the Resolver would resolve to the current page name) * The 3rd parameter is an Entity Reference that will be used to fill the parts of the reference that we don't specify (namely the wiki reference and the space references) ))) * Resolve a group name (##XWikiAllGroup## in the example), as a DocumentReference:((( {{code language="velocity"}} #set ($groupReference = $services.model.resolveDocument('XWikiAllGroup', 'group')) {{/code}} )))GNU Lesser General Public License 2.1http://extensions.xwiki.org/xwiki/bin/view/Extension/Model%20ModuleXWiki Development Teamhttps://xwiki.org/xwiki/bin/view/XWiki/XWikiTeamgitgit://github.com/xwiki/xwiki-platform.git/xwiki-platform-core/xwiki-platform-modelgitgit@github.com:xwiki/xwiki-platform.git/xwiki-platform-core/xwiki-platform-modelhttps://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-model/jirahttps://jira.xwiki.org/browse/XWIKIfalsemaven.groupidorg.xwiki.platformmaven.artifactidxwiki-platform-modelmaven.Modelorg.xwiki.platform:xwiki-platform-model:pom:18.9.0xwiki.extension.recommendedVersions.commonsorg.xwiki.commons:.*/[18.9.0]xwiki.extension.recommendedVersions.platformorg.xwiki.commons:.*/[18.9.0], org.xwiki.rendering:.*/[18.9.0], org.xwiki.platform:.*/[18.9.0]xwiki.extension.recommendedVersionsorg.xwiki.commons:.*/[18.9.0], org.xwiki.rendering:.*/[18.9.0], org.xwiki.platform:.*/[18.9.0]4.2-milestone-3maven-xwikihttps://nexus.xwiki.org/nexus/content/groups/publicmaven