Custom Mapping

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.

Making use of custom mapping is a 3 step process:

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).

   You can also use the Custom Mapping Application extension to generate the hbm file.

   Example Mapping file (mailinglist.hbm.xml):

   <?xml version="1.0"?>
   <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD//EN"
           "http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">
   <hibernate-mapping>
      <class entity-name="Mailing.MailingMemberClass" table="mailing">
          <id name="id" type="long" unsaved-value="undefined">
              <column name="xwo_id" not-null="true" />
              <generator class="assigned" />
          </id>
          <property name="member" type="text"><column name="mam_member" /></property>
          <property name="to" type="text"><column name="mam_to" /></property>
          <property name="from" type="text"><column name="mam_from" /></property>
          <property name="subject" type="text"><column name="mam_subject" /></property>
          <property name="smtphost" type="text"><column name="mam_smtphost" /></property>
          <property name="mailing" type="text"><column name="mam_mailing" /></property>
          <property name="status" type="text"><column name="mam_status" /></property>
          <property name="body" type="text"><column name="mam_body" /></property>
          <property name="alternative" type="text"><column name="mam_alternative" /></property>
           </class>
   </hibernate-mapping>
2. Reference your hbm.xml file in the Hibernate configuration file located in WEB-INF/hibernate.cfg.xml, by adding a mapping element. For example:
   <mapping resource="/some/package/mailinglist.hbm.xml"/>
3. 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.
   {{groovy}}
   classDocumentName = "Mailing.MailingMemberClass";
   classDoc = xwiki.getDocument(classDocumentName).getDocument();
   xml = classDoc.getxWikiClassXML();
   if (xml == null || "".equals(xml)) {
       println("The document [" + classDocumentName + "] doesn't seem to "
              + ((classDoc.isNew()) ? "exist." : "contain a class."));
   } else {
       classDoc.getxWikiClass().setCustomMapping("internal");
       xcontext.getContext().getWiki().saveDocument(classDoc, xcontext.getContext());
       classDoc = xwiki.getDocument(classDocumentName).getDocument();
      if ("internal".equals(classDoc.getxWikiClass().getCustomMapping())) {
           println("Success.");
      } else {
           println("Failed to alter the custom mapping field.");
      }
   }
   {{/groovy}}

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.