xwiki开发者指南-自定义映射

自定义映射允许将XWiki类（XClass）映射到数据库表（相对于未映射XClasses，使用标准的，预定义的XWiki table scheme）。自定义映射可用于提高性能（当一个类有大量实例的时候），或者共享外部数据（企业数据，或其他软件的数据）。
使用自定义映射是一个3步过程： 

1. 在一个hbm.xml文件中，为你XClass定义Hibernate映射(见下面的例子)。此文件要放在CLASSPATH下(WEB-INF/classes或者打包为JAR文件放在WEB-INF/lib下)

   你也可以使用自定义映射应用程序生成hbm文件。

   例如映射文件(mailinglist.hbm.xml):

   <?xml version="1.0"?>
   <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD//EN"
           "http://hibernate.sourceforge.net/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. 在位于WEB-INF/hibernate.cfg.xml下的Hibernate配置文件里通过添加mapping元素来引用你的hbm.xml文件。例如：

   <mapping resource="/some/package/mailinglist.hbm.xml"/>

3. 最后，对于已写入mapping的XClass应设置为包含一个custom mapping。遗憾的是目前还没有办法在XWiki Enterprise用户界面设置，所以你必须以编程方式来设置它。下面这一段Groovy代码就可以解决这个问题（请记住，要执行Groovy代码，包含代码的页面应该被有该文档的编程权限的用户来保存）。注意，这也可以用一个Java组件来完成。

   {{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}}

一旦这3个步骤完成，加载和保存XClass会在数据库生成你在Hibernate映射文件中定义的表。

从XWiki3.5.2，4.1.4和4.2M3开始，复制一个包含自定义映射类的文档不会复制它的类自定义映射。这是为了避免新创建的类不可用，与映射不一致。