Wiki source code of Custom Mapping
Last modified by Alex Cotiugă on 2022/10/12
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
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. |
 |
1.1 | 2 | |
| 3 | Making use of custom mapping is a 3 step process: | ||
 |
5.4 | 4 | |
| |
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 | |||
| |
7.5 | 7 | {{info}}You can also use the [[Custom Mapping Application>>extensions:Extension.Custom mapping tool]] extension to generate the ##hbm## file.{{/info}} |
 |
7.4 | 8 | |
| |
1.1 | 9 | Example Mapping file (##mailinglist.hbm.xml##): |
 |
1.2 | 10 | |
| |
1.1 | 11 | {{code language="xml"}} |
| 12 | <?xml version="1.0"?> | ||
| 13 | <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD//EN" | ||
 |
10.1 | 14 | "http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd"> |
| |
1.1 | 15 | <hibernate-mapping> |
| 16 | <class entity-name="Mailing.MailingMemberClass" table="mailing"> | ||
| |
6.1 | 17 | <id name="id" type="long" unsaved-value="undefined"> |
| |
7.1 | 18 | <column name="xwo_id" not-null="true" /> |
| |
6.1 | 19 | <generator class="assigned" /> |
| 20 | </id> | ||
| |
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}} | ||
| |
1.2 | 33 | |
| |
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 | ))) | ||
| |
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. |
| |
5.2 | 41 | ((( |
 |
3.1 | 42 | {{code language="java"}} |
| |
1.1 | 43 | {{groovy}} |
| |
3.1 | 44 | classDocumentName = "Mailing.MailingMemberClass"; |
| 45 | classDoc = xwiki.getDocument(classDocumentName).getDocument(); | ||
| |
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.")); | ||
| |
3.1 | 50 | } else { |
| |
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 | } | ||
| |
3.1 | 59 | } |
| |
1.1 | 60 | {{/groovy}} |
| 61 | {{/code}} | ||
| |
5.2 | 62 | ))) |
| |
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. | ||
 |
5.3 | 65 | |
| |
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}} |
