4:16 a.m.
Author: dkatayev
Date: 2010-08-05 05:16:13 -0400 (Thu, 05 Aug 2010)
New Revision: 2880
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq/
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq/jcr-faq.xml
Modified:
jcr/branches/1.12.x/docs/reference/en/pom.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/master.xml
Log:
EXOJCR-625 JCR FAQ ported to docbook format
Modified: jcr/branches/1.12.x/docs/reference/en/pom.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/pom.xml 2010-08-05 09:13:56 UTC (rev 2879)
+++ jcr/branches/1.12.x/docs/reference/en/pom.xml 2010-08-05 09:16:13 UTC (rev 2880)
@@ -99,11 +99,11 @@
<stylesheetResource>classpath:/xslt/org/exojcr/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
</format>
- <!-- format>
+ <!--format>
<formatName>pdf</formatName>
<stylesheetResource>classpath://xslt/org/exojcr/pdf.xsl</stylesheetResource>
<finalName>${pom.name}.pdf</finalName>
- </format -->
+ </format-->
<!-- format>
<formatName>eclipse</formatName>
<stylesheetResource>classpath:/xslt/org/exojcr/eclipse.xsl</stylesheetResource>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/master.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/master.xml 2010-08-05
09:13:56 UTC (rev 2879)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/master.xml 2010-08-05
09:16:13 UTC (rev 2880)
@@ -66,9 +66,9 @@
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="modules/ws.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="modules/faq.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-
-
</book>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq/jcr-faq.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq/jcr-faq.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq/jcr-faq.xml 2010-08-05
09:16:13 UTC (rev 2880)
@@ -0,0 +1,714 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.FAQ">
+ <?dbhtml filename="ch-jcr-faq.html"?>
+
+ <title>JCR FAQ</title>
+
+ <para>It's the draft for a future FAQ of JCR usage.</para>
+
+ <section>
+ <title>Kernel</title>
+
+ <section>
+ <title>What is the best, standardized way to get the instance of a
+ service ?</title>
+
+
<programlisting>container.getComponentInstanceOfType(ServiceName.class);</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>JCR</title>
+
+ <section>
+ <title>JCR core</title>
+
+ <section>
+ <title>Is it better to use Session.getNodeByUUID or
+ Session.getItem?</title>
+
+ <para>Session.getNodeByUUID() about 2.5 times faster of
+ Session.getItem(String) and only 25% faster of Node.getNode(String).
+ See the daily tests results for such comparisons, e.g.</para>
+
+ <para><ulink
+
url="http://tests.exoplatform.org/JCR/1.12.2-GA/rev.2442/daily-perfo...
+ </section>
+
+ <section>
+ <title>Does it make sense to have all the node referencable to use
+ getNodeByUUID all the time?</title>
+
+ <para>Until it's applicable for a business logic it can be. But take
+ in account the paths are human readable and lets you think in
+ hierarchy. If it's important a location based approach is
+ preferable.</para>
+ </section>
+
+ <section>
+ <title>What should I use to check if an Item exists before getting the
+ Value?</title>
+
+ <para>Use Session.itemExists(String absPath), Node.hasNode(String
+ relPath) or Property.hasProperty(String name). It's also is possible
+ to check Node.hasNodes() and Node.hasProprties().</para>
+ </section>
+
+ <section>
+ <title>How to use Observation properly?</title>
+
+ <para>JCR Observation it's a way to listen on persistence changes of a
+ Repository. It provides several options to configure the listener for
+ an interesting only changes. For proper use it's important to
+ understand concept of events filtering for a registered EventListener
+ (8.3.3 Observation Manager). An often confusing part it's the
+ <emphasis role="bold">absPath</emphasis>, it's an
associated parent of
+ a location you want to observe events on. I.e. it's a parent of child
+ node(s) or this parent property(ies); if <emphasis
+ role="bold">isDeep</emphasis> is true then you'll get
events of all
+ the subtree of child nodes also. Same actual for <emphasis
+ role="bold">uuid</emphasis> and <emphasis
+ role="bold">nodeTypeName</emphasis> parameters of
+ ObservationManager.addEventListener() method.</para>
+ </section>
+
+ <section>
+ <title>Is it better to use queries that to access the data by the JCR
+ API?</title>
+
+ <para>No, direct access to items via JCR API is more efficient. Search
+ will consume additional resources for index querying and only then
+ return the items.</para>
+ </section>
+
+ <section>
+ <title>What is default query ordering?</title>
+
+ <para>By default (if query do not contains any ordering statements)
+ result nodes is sorted by document order.</para>
+ </section>
+
+ <section>
+ <title>Is ordering by jcr:path or Item name supported?</title>
+
+ <para>No it does not supported There is two ways to ordering results,
+ when path may be used as criteria:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>order by property with value type NAME or PATH (jcr supports
+ it)</para>
+ </listitem>
+
+ <listitem>
+ <para>order by jcr:path - sort by exact path of node (jcr do not
+ supports it)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Order by jcr:path</para>
+
+ <para>If no order specification is supplied in the query statement,
+ implementations may support document order on the result nodes (see
+ 6.6.4.2 Document Order). And its sorted by order number.</para>
+
+ <para>By default (if query do not contains any ordering statements)
+ result nodes is sorted by document order.</para>
+
+ <programlisting>SELECT * FROM nt:unstructured WHERE jcr:path LIKE
'testRoot/%'</programlisting>
+
+ <para>For specified jcr:path ordering there is different proceeding in
+ XPath and SQL:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>SQL no matter ascending or descending - query returns result
+ nodes in random order: {code}SELECT * FROM nt:unstructured WHERE
+ jcr:path LIKE 'testRoot/%' ORDER BY jcr:path{code}</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>XPath - jcr:path order construction is ignored (so result is
+ not sorted according path); {code}/testRoot/* <ulink
+
url="@jcr:primaryType='nt:unstructured'">@jcr:primaryType='nt:unstructured'</ulink>
+ order by jcr:path{code}</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>How eXo JCR indexer uses content encoding?</title>
+
+ <para>1. Indexer uses jcr:encoding property of nt:resource node (used
+ as jcr:content child node of nt:file) 2. if no jcr:encoding property
+ set the Document Service will use the one configured in the service
+ (defaultEncoding) 3. if has nothing configured a JVM default encoding
+ will be used</para>
+ </section>
+
+ <section>
+ <title>Which database server is better for eXo JCR?</title>
+
+ <para>If question is a performance it's difficult question, as each
+ database can be configured to be more (and more) faster for each
+ special case. MySQL with MyISAM engine will be faster. But MySQL has
+ limitations for indexes for multilingual columns (Item names
+ actually). So, with long Item names (larger ofOracle or PostgreSQL
+ also are good for performance. DB2 and MSSQL slower in default
+ configurations. Default configuration of Sybase leader of slowness.
+ But in this question take the database server maintenance in account.
+ MySQL and PostgreSQL are simple in installation and can works even on
+ limited hardware. Oracle, DB2, MSSQL or Sybase need more efforts. Same
+ actual for maintenance during the work. Note for Sybase:
+ "check-sns-new-connection" data container configuration parameter
+ should be set to "true". For testing or embedded use HSQLDB is the
+ best. Apache Derby and H2 also supported. But H2 surprisingly needs
+ "beta" feature enabled - MVCC=TRUE in JDBC url.</para>
+ </section>
+
+ <section>
+ <title>How to setup eXo JCR for mutilingial content on
MySQL?</title>
+
+ <para>MySQL database should be configured to use single-byte encoding,
+ e.g. "latin1". eXo JCR application (e.g. GateIn) should use JCR
+ dialect "MySQL-UTF8".</para>
+
+ <para>In other words: MySQL database default encoding and JCR dialect
+ cannot be UTF8 both. Use single-byte encoding (e.g. "latin1") for
+ database and "mysql-utf8" dialect for eXo JCR.</para>
+
+ <para>Notice: "MySQL-UTF8" dialect cannot be auto-detected, it
should
+ be set explicitly in configuration.</para>
+ </section>
+
+ <section>
+ <title>Does MySQL has limitation affecting eXo JCR features?</title>
+
+ <para>Index's key length of JCR_SITEM (JCR_MITEM) table for mysql-utf8
+ dialect is reduced to 765 bytes (or 255 chars).</para>
+ </section>
+
+ <section>
+ <title>Does use of Sybase database needs special options in eXo JCR
+ configuration?</title>
+
+ <para>For properly work JCR with Sybase need for each workspace data
+ container add new property "check-sns-new-connection" with false value
+ like this:</para>
+
+ <programlisting><container
class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr" />
+ <property name="dialect" value="auto" />
+ <property name="multi-db" value="true" />
+ <property name="update-storage" value="false" />
+ <property name="max-buffer-size" value="200k" />
+ <property name="swap-directory"
value="target/temp/swap/ws" />
+ <property name="swap-directory"
value="target/temp/swap/ws" />
+ <property name="check-sns-new-connection" value="false"
/>
+ </properties></programlisting>
+ </section>
+
+ <section>
+ <title>How to open and close a session properly to avoid memory
+ leaks?</title>
+
+ <programlisting>Session session = repository.login(credentials);
+try
+{
+// here your code
+}
+finally
+{
+session.logout();
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Can I use Session after logout?</title>
+
+ <para>No. Any instance of Session or Node (acquired through session)
+ shouldn't be used after logout anymore. At least it is highly
+ recommended not to use.</para>
+ </section>
+
+ <section>
+ <title>How to configure jcr for cluster ?</title>
+
+ <para>So we have configured JCR in standalone mode and want to
+ reconfigure it for clustered environment. First of all let's check
+ whether all requirements are satisfied:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Dedicated RDBMS anyone like MySQL, Postges, Oracle and etc.
+ but just not HSSQL;</para>
+ </listitem>
+
+ <listitem>
+ <para>Shared storage. The simples thing is to use shared FS like
+ NFS or SMB mounted in operation system, but they are rather slow.
+ The best thing is to use SAN (Storage Area Network);</para>
+ </listitem>
+
+ <listitem>
+ <para>Fast network between JCR nodes.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>So now, need to configure Container a bit. Check
+ exo-configuration.xml to be sure You are using JBossTS Transaction
+ Service and JBossCache Transaction Manager, as shown below.</para>
+
+ <programlisting><component>
+
<key>org.jboss.cache.transaction.TransactionManagerLookup</key>
+
<type>org.jboss.cache.GenericTransactionManagerLookup</type>
+</component>
+
+<component>
+
<key>org.exoplatform.services.transaction.TransactionService</key>
+
<type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type>
+ <init-params>
+ <value-param>
+ <name>timeout</name>
+ <value>300</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+
+ <para>Next stage is actually the JCR configuration. We need JBossCache
+ configuration templates for : data-cache, indexer-cache and
+ lock-manager-cache. Later they will be used configuring JCR's core
+ components. There are pre-bundled templates in EAR or JAR in
+ conf/standalone/cluster. They can be used as is or re-written if
+ needed. And now time to re-configure a bit each workspace. Actually
+ need to change few parameters of <cache>,
<query-handler>
+ and <lock-manager>.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><cache> configuration should looks like
this:</para>
+
+ <programlisting><cache enabled="true"
+
class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">
+ <properties>
+ <property name="jbosscache-configuration"
value="test-jbosscache-data.xml" />
+ <property name="jgroups-configuration"
value="udp-mux.xml" />
+ <property name="jgroups-multiplexer-stack"
value="true" />
+ <property name="jbosscache-cluster-name"
value="JCR-cluster-db1-ws" />
+ </properties>
+</cache></programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>"jbosscache-configuration" is the path to
configuration
+ template;</para>
+ </listitem>
+
+ <listitem>
+ <para>"jgroups-configuration" is path to JGroups
configuration
+ is multiplexer stack is used (default). This file is also
+ pre-bundled with templates and is recommended for use;</para>
+ </listitem>
+
+ <listitem>
+ <para>"jgroups-multiplexer-stack" just simply
"true". Strongly
+ recommended;</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cluster-name" is the name of cluster
group.
+ Should be different for each workspace and each workspace
+ component. I.e.:
+
<repository_name>-<ws_name>-<component(cache\|lock\|index)></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para><query-handler> configuration</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You must replace or add in <query-handler>
block
+ the "changesfilter-class" parameter equals with:</para>
+
+ <programlisting><property
name="changesfilter-class"
value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter"/></programlisting>
+ </listitem>
+
+ <listitem>
+ <para>add JBossCache-oriented configuration:</para>
+
+ <programlisting><property
name="jbosscache-configuration" value="test-jbosscache-indexer.xml"
/>
+<property name="jgroups-configuration" value="udp-mux.xml"
/>
+<property name="jgroups-multiplexer-stack" value="true"
/>
+<property name="jbosscache-cluster-name"
value="JCR-cluster-indexer-db1-ws" />
+<property name="max-volatile-time" value="60"
/></programlisting>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>Those properties have the same meaning and restrictions as in
+ previous block. Last property "max-volatile-time" is not mandatory but
+ recommended. This notifies that latest changes in index will be
+ visible for each cluster node not later than in 60s.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><lock-manager> configuration</para>
+
+ <para>Maybe this is the hardest element to configure, because we
+ have to define access to DB where locks will be stored. Replace
+ exsiting lock-manager configuration with shown below.</para>
+
+ <programlisting>
+<lock-manager
class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">
+ <properties>
+ <property name="time-out" value="15m" />
+ <property name="jbosscache-configuration"
value="test-jbosscache-lock.xml" />
+ <property name="jgroups-configuration"
value="udp-mux.xml" />
+ <property name="jgroups-multiplexer-stack" value="true"
/>
+ <property name="jbosscache-cluster-name"
value="JCR-cluster-locks-db1-ws" />
+ <property name="jbosscache-cl-cache.jdbc.table.name"
value="jcrlocks_db1_ws" />
+ <property name="jbosscache-cl-cache.jdbc.table.create"
value="true" />
+ <property name="jbosscache-cl-cache.jdbc.table.drop"
value="false" />
+ <property name="jbosscache-cl-cache.jdbc.table.primarykey"
value="jcrlocks_db1_ws_pk" />
+ <property name="jbosscache-cl-cache.jdbc.fqn.column"
value="fqn" />
+ <property name="jbosscache-cl-cache.jdbc.node.column"
value="node" />
+ <property name="jbosscache-cl-cache.jdbc.parent.column"
value="parent" />
+ <property name="jbosscache-cl-cache.jdbc.datasource"
value="jdbcjcr" />
+ </properties>
+</lock-manager>
+
+</programlisting>
+
+ <para>First few properties are the same as in previous components,
+ but here you can see some strange "jbosscache-cl-cache.jdbc.*"
+ properties. They define access parameters for database where lock
+ are persisted.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.table.create" - whether
to
+ create it or not. Usually "true";</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.table.drop" - whether to
drop
+ on a start or not. Use "false";</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.table.primarykey" - name
of
+ column with pk;</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.fqn.column" - name of one
more
+ column, use as in example if not sure (if much interested,
+ please refer to JBossCache JDBCCacheLoader
+ documentation)</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.node.column" - name of
one
+ more column, use as in example if not sure (if much
+ interested, please refer to JBossCache JDBCCacheLoader
+ documentation)</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.parent.column" - name of
one
+ more column, use as in example if not sure (if much
+ interested, please refer to JBossCache JDBCCacheLoader
+ documentation)</para>
+ </listitem>
+
+ <listitem>
+ <para>"jbosscache-cl-cache.jdbc.datasource" - name of
+ configured in Container datasource, where you want to store
+ locks. Bets idea is to use the same as used for
+ workspace.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>That's all. JCR is ready for running in a cluster.</para>
+ </section>
+
+ <section>
+ <title>Is JCR suitable for remote sites\* synchronization</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>understand remote site as different buildings separated by a
+ WAN network.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>How to use lucene spellchecker?</title>
+
+ <para>There is few steps:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>enable lucene spellchecker in jcr QueryHandler
+ configuration:</para>
+
+ <programlisting><query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ ...
+ <property name="spellchecker-class"
value="org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$FiveSecondsRefreshInterval"
/>
+ ...
+ </properties>
+</query-handler></programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>execute query with rep:spellcheck function and word that is
+ checked:</para>
+
+ <programlisting>Query query = qm.createQuery("select
rep:spellcheck() from nt:base where " + "jcr:path = '/' and
spellcheck('word that is checked')", Query.SQL);
+RowIterator rows = query.execute().getRows();</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>fetch a result:</para>
+
+ <programlisting>Row r = rows.nextRow();
+Value v = r.getValue("rep:spellcheck()");</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>If there is no any results, that means there is no suggestion,
+ so word is correct or spellcheckers dictionary do not contain any word
+ looking like checked word.</para>
+ </section>
+
+ <section>
+ <title>How can I affect to spellchecker results?</title>
+
+ <para>There is two parameters in jcr QueryHandler
+ configuration:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>minimal distance between checked word and proposed
+ suggestion;</para>
+ </listitem>
+
+ <listitem>
+ <para>search for more popular suggestions;</para>
+
+ <programlisting><query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ ...
+ <property name="spellchecker-class"
value="org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$FiveSecondsRefreshInterval"
/>
+ <property name="spellchecker-more-popular" value="false"
/>
+ <property name="spellchecker-min-distance" value="0.55"
/>
+ ...
+ </properties>
+</query-handler></programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>Minimal distance is counted as Levenshtein distance between
+ checked word and spellchecker suggestion.</para>
+
+ <para>MorePopular paramter affects in next way: If "morePopular"
+ disabled:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>if the proposed word exist in the directory - no suggestion
+ given;</para>
+ </listitem>
+
+ <listitem>
+ <para>if the proposed word doesn't exist in the directory -
+ propose the closed word;</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If "morePopular" enabled:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>no matter word exist or not, checker will propose the closed
+ word that is the most popular than checked word.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section>
+ <title>JCR extensions</title>
+
+ <section>
+ <title>How to restore repository to existing repository ?</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Remove existing repository, use :</para>
+
+ <programlisting>RepositoryService.removeRepository(String
repositoryName)</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Restore repository, use</para>
+
+ <programlisting>BackupManager.restore(RepositoryBackupChainLog log,
RepositoryEntry repositoryEntry, boolean asynchronous)</programlisting>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>How to restore workspace to existing worksapce ?</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Remove existing workspace, use :</para>
+
+ <programlisting>ManageableRepository.removeWorkspace(String
workspaceName)</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Restore workspace, use :</para>
+
+ <programlisting>BackupManager.restore(BackupChainLog log, String
repositoryName, WorkspaceEntry workspaceEntry, boolean
asynchronous)</programlisting>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Does JCR support hot backup ?</title>
+
+ <para>Yes, JCR is support hot backup. Will use
+ org.exoplatform.services.jcr.ext.backup.BackupManager.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>WebDAV</title>
+
+ <section>
+ <title>I uploaded a file to WebDAV server using Mac OS Finder, but the
+ file size is '0', what is wrong ?</title>
+
+ <para>This is a known finder bug started from Mac OS v.10.5.3 and not
+ yet fixed, .</para>
+
+ <para>for more details follow:&nbsp; <ulink
+
url="http://discussions.apple.com/thread.jspa?threadID=1538882&a...
+ Disscussion thread.</ulink></para>
+ </section>
+
+ <section>
+ <title>Can I manage 'cache-control' value for different
media-types
+ from server configuration ?</title>
+
+ <para>Use "cache-control" configuration parameter.</para>
+
+ <para>The value of this parameter must contain colon-separated pairs
+ "MediaType:cache-control value"</para>
+
+ <para>For example if you need to cache all text/xml and text/plain
+ files for 5 minutes (300 sec.) and other text/\* files for 10 minutes
+ (600 sec.) use the next configuration:</para>
+
+ <programlisting><component>
+
<type>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</type>
+ <init-params>
+ <value-param>
+ <name>cache-control</name>
+
<value>text/xml,text/plain:max-age=300;text/*:max-age=600;</value>
+ </value-param>
+ <init-params>
+<component>
+</programlisting>
+ </section>
+
+ <section>
+ <title>How to perform WebDAV requests using curl ?</title>
+
+ <para>Simple Requests</para>
+
+ <para>For simple request such as: GET, HEAD, MKCOL, COPY, MOVE,
+ DELETE, CHECKIN, CHECKOUT, UNCHECKOUT, LOCK, UNLOCK, VERSIONCONTROL,
+ OPTIONS</para>
+
+ <para>perform:</para>
+
+ <programlisting>curl -i -u 'user:pass' -X 'METHOD_NAME'
'resource_url'</programlisting>
+
+ <para>for example to create a folder named test perform:</para>
+
+ <programlisting>curl -i -u 'root:exo' -X MKCOL
'http://localhost:8080/rest/jcr/repository/production/test</programlisting>
+
+ <para>to PUT a test.txt file from your current folder to "test
"folder
+ on server perform:</para>
+
+ <programlisting>curl -i -u 'root:exo' -X PUT
'http://localhost:8080/rest/jcr/repository/production/test/test.txt' -d
@test.txt</programlisting>
+
+ <para>Requests with XML body</para>
+
+ <para>For requests which contains xml body such as: ORDER, PROPFIND,
+ PROPPATCH, REPORT, SEARCH</para>
+
+ <para>add <emphasis role="bold">-d 'xml_body
text'</emphasis> or
+ <emphasis role="bold">-d @body.xml</emphasis></para>
+
+ <para>(body.xml must contain a valid xml request bidy.) to you
+ curl-command:</para>
+
+ <programlisting>curl -i -u 'user:pass' -X 'METHOD_NAME' -H
'Headers' 'resource_url' -d 'xml_body
text'</programlisting>
+
+ <para>for example to find all files containing "test"
perform:</para>
+
+ <programlisting>curl -i -u "root:exo" -X "SEARCH"
"http://192.168.0.7:8080/rest/jcr/repository/production/" -d
+"<?xml version='1.0' encoding='UTF-8' ?>
+ <D:searchrequest xmlns:D='DAV:'>
+ <D:sql>SELECT * FROM nt:base WHERE contains(*,
'text')</D:sql>
+</D:searchrequest>"</programlisting>
+
+ <para>if you need to add some headers to your request use \-H
+ key.</para>
+
+ <para>More information about methods parameters you can find in <ulink
+ url="http://www.ietf.org/rfc/rfc2518.txt">HTTP Extensions for
+ Distributed Authoring</ulink> specification.</para>
+ </section>
+
+ <section>
+ <title>How eXo JCR WebDAV server treats content encoding?</title>
+
+ <para>OS client (Windows, Linux etc) doesn't set an encoding in a
+ request. But eXo JCR WebDAV server looks for an encoding in a
+ Content-Type header and set it to jcr:encoding. See <ulink
+
url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html,"&g...
+ 14.17 Content-Type. e.g. Content-Type: text/html; charset=ISO-8859-4
+ So, if a client will set Content-Type header, e.g. JS code from a
+ page, it will works for a text file as expected.</para>
+
+ <para>If WebDAV request doesn't contain a content encoding it's
+ possible to write a dedicated action in a customer application. The
+ action will set jcr:encoding using its own logic, e.g. based on IP or
+ user preferences.</para>
+ </section>
+ </section>
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/faq.xml 2010-08-05
09:16:13 UTC (rev 2880)
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<part>
+ <?dbhtml filename="part-faq.html"?>
+
+ <title>Frequently Asked Question</title>
+
+ <xi:include href="faq/jcr-faq.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>