Hide last authors
Ecaterina Moraru (Valica) 8.1 1 Custom Mapping allows to map a XWiki Class (XClass) to its own database table (as opposed to XClasses that are not mapped and that use the standard, predefined, XWiki table scheme). Custom mapping can be useful for improving performances (when expecting a class to have a large number of instances for example), or for sharing external data (sensitive data, or other software data for example) with XWiki.
Vincent Massol 1.1 2
3 Making use of custom mapping is a 3 step process:
Manuel Smeria 5.4 4
Vincent Massol 1.1 5 1. Define the actual Hibernate mapping for your XClass, in a ##hbm.xml## file (see the example below). This file should then be made available somewhere in the CLASSPATH (##WEB-INF/classes## or in your own JAR file that you put in ##WEB-INF/lib##).(((
6
Vincent Massol 7.5 7 {{info}}You can also use the [[Custom Mapping Application>>extensions:Extension.Custom mapping tool]] extension to generate the ##hbm## file.{{/info}}
Djebloun Sidali 7.4 8
Vincent Massol 1.1 9 Example Mapping file (##mailinglist.hbm.xml##):
Jerome 1.2 10
Vincent Massol 1.1 11 {{code language="xml"}}
12 <?xml version="1.0"?>
13 <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD//EN"
14 "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
15 <hibernate-mapping>
16 <class entity-name="Mailing.MailingMemberClass" table="mailing">
Sebastian Knoche 6.1 17 <id name="id" type="long" unsaved-value="undefined">
Sebastian Knoche 7.1 18 <column name="xwo_id" not-null="true" />
Sebastian Knoche 6.1 19 <generator class="assigned" />
20 </id>
Vincent Massol 1.1 21 <property name="member" type="text"><column name="mam_member" /></property>
22 <property name="to" type="text"><column name="mam_to" /></property>
23 <property name="from" type="text"><column name="mam_from" /></property>
24 <property name="subject" type="text"><column name="mam_subject" /></property>
25 <property name="smtphost" type="text"><column name="mam_smtphost" /></property>
26 <property name="mailing" type="text"><column name="mam_mailing" /></property>
27 <property name="status" type="text"><column name="mam_status" /></property>
28 <property name="body" type="text"><column name="mam_body" /></property>
29 <property name="alternative" type="text"><column name="mam_alternative" /></property>
30 </class>
31 </hibernate-mapping>
32 {{/code}}
Jerome 1.2 33
Vincent Massol 1.1 34 )))
35 1. Reference your ##hbm.xml## file in the Hibernate configuration file located in ##WEB-INF/hibernate.cfg.xml##, by adding a ##mapping## element. For example:(((
36 {{code language="xml"}}
37 <mapping resource="/some/package/mailinglist.hbm.xml"/>
38 {{/code}}
39 )))
Ecaterina Moraru (Valica) 9.1 40 1. Last, the XClass for which the mapping has been written should be set as containing a custom mapping. Unfortunately there's currently no way to set this using the XWiki UI so you'll have to set it programmatically. The following Groovy snippet will do the trick (Remember that for Groovy code to be executed, the page that contains the code should be saved by a user having the programming right allowed on that document). Note that this could also be done in a Java component.
Vincent Massol 5.2 41 (((
Caleb James DeLisle 3.1 42 {{code language="java"}}
Vincent Massol 1.1 43 {{groovy}}
Caleb James DeLisle 3.1 44 classDocumentName = "Mailing.MailingMemberClass";
45 classDoc = xwiki.getDocument(classDocumentName).getDocument();
Caleb James DeLisle 5.1 46 xml = classDoc.getxWikiClassXML();
47 if (xml == null || "".equals(xml)) {
48 println("The document [" + classDocumentName + "] doesn't seem to "
49 + ((classDoc.isNew()) ? "exist." : "contain a class."));
Caleb James DeLisle 3.1 50 } else {
Caleb James DeLisle 5.1 51 classDoc.getxWikiClass().setCustomMapping("internal");
52 xcontext.getContext().getWiki().saveDocument(classDoc, xcontext.getContext());
53 classDoc = xwiki.getDocument(classDocumentName).getDocument();
54 if ("internal".equals(classDoc.getxWikiClass().getCustomMapping())) {
55 println("Success.");
56 } else {
57 println("Failed to alter the custom mapping field.");
58 }
Caleb James DeLisle 3.1 59 }
Vincent Massol 1.1 60 {{/groovy}}
61 {{/code}}
Vincent Massol 5.2 62 )))
Vincent Massol 1.1 63
64 Once these 3 steps have been done, loading and saving of your XClass will go in the table you've defined in your custom Hibernate mapping file.
Denis Gervalle 5.3 65
Manuel Smeria 5.4 66 {{info}}
67 Since XWiki 3.5.2, 4.1.4, and 4.2M3, copying a document containing a custom mapped class does not make the copied class custom mapped anymore. This has been introduced to avoid the newly created class to be unusable and inconsistent with the available mapping.
68 {{/info}}

Get Connected