sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [CONF] Apache Sling > Content Loading
Date Wed, 28 Oct 2009 10:45:00 GMT
    <base href="">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLING&amp;forWysiwyg=true"
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="">Content
     <h4>Page <b>edited</b> by             <a href="">Vidar
S. Ramdal</a>
     Updated to reflect change in SLING-1165
          <div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
     Updated to reflect change in SLING-1165<br />
     <div class="notificationGreySide">
         <h1><a name="ContentLoading-ContentLoadingandNodetypeSupport"></a>Content
Loading and Nodetype Support</h1>

<p>Apache Sling provides support for initial content loading into a repository and for
registering node types. The <tt>sling-jcr-contentloader</tt> bundle provides loading
of content from a bundle into the repository and the <tt>sling-jcr-base</tt> bundle
provides node type registration.</p>

<h2><a name="ContentLoading-InitialContentLoading"></a>Initial Content Loading</h2>

<p>Bundles can provide initial content, which is loaded into the repository when the
bundle has entered the <em>started</em> state. Such content is expected to be
contained in the bundles accessible through the Bundle entry API methods. Content to be loaded
is declared in the <tt>Sling-Initial-Content</tt> bundle manifest header. This
header takes a comma-separated list of bundle entry paths. Each entry and all its child entries
are accessed and entered into starting with the child entries of the listed entries.</p>

<p>Adding this content preserves the paths of the entries as show in this table, which
assumes a <tt>Sling-Initial-Content</tt> header entry of <tt>SLING-INF/content</tt>:</p>
<table class='confluenceTable'><tbody>
<th class='confluenceTh'> Entry </th>
<th class='confluenceTh'> Repository Path </th>
<td class='confluenceTd'> <tt>SLING-INF/content/home</tt> </td>
<td class='confluenceTd'> <tt>/home</tt> </td>
<td class='confluenceTd'> <tt>SLING-INF/content/content/playground/en/home</tt>
<td class='confluenceTd'> <tt>/content/playground/en/home</tt> </td>
<p>Bundle entries are installed as follows:</p>
<table class='confluenceTable'><tbody>
<th class='confluenceTh'> Entry Type </th>
<th class='confluenceTh'> Installation method </th>
<td class='confluenceTd'> Directory </td>
<td class='confluenceTd'> Created as a node of type <tt>nt:folder</tt> unless
a content definition file of the same name exists in the same directory as the directory to
be installed. Example: A directory <tt>SLING-INF/content/dir</tt> is installed
as node <tt>/dir</tt> of type <tt>nt:folder</tt> unless a <tt>SLING-INF/content/dir.xml</tt>
or <tt>SLING-INF/content/dir.json</tt> file exists which defines the content for
the <tt>/dir</tt> node. </td>
<td class='confluenceTd'> File </td>
<td class='confluenceTd'> Unless the file is a content definition file (see below) an
<tt>nt:file</tt> node is created for the file and an <tt>nt:resource</tt>
node is created as its <tt>jcr:content</tt> child node to take the contents of
the bundle file. The properties of the <tt>nt:resource</tt> node are set from
file information as available. If the file is a content definition file, the content is created
as defined in the file. See below for the content definition file specification. </td>
<p>It is possible to modify the intial content loading default behaviour by using certain
optional directives. Directives should be specified separated by semicolon. They are defined
as follows:</p>
<table class='confluenceTable'><tbody>
<th class='confluenceTh'> Directive </th>
<th class='confluenceTh'> Definition </th>
<th class='confluenceTh'> Default value </th>
<th class='confluenceTh'> Description </th>
<td class='confluenceTd'> <tt>overwrite</tt> </td>
<td class='confluenceTd'> <tt>overwrite:=(true&#124;false)</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> The overwrite directive specifies if content should be overwritten
or just initially added. </td>
<td class='confluenceTd'> <tt>uninstall</tt> </td>
<td class='confluenceTd'> <tt>uninstall:=(true&#124;false)</tt> </td>
<td class='confluenceTd'> <tt>overwrite</tt> </td>
<td class='confluenceTd'> The uninstall directive specifies if content should be uninstalled
when bundle is unregistered. This value defaults to the value of the <tt>overwrite</tt>
directive. </td>
<td class='confluenceTd'> <tt>path</tt> </td>
<td class='confluenceTd'> <tt>path:=<em>/target/location</em></tt>
<td class='confluenceTd'> <tt>/</tt> </td>
<td class='confluenceTd'> The path directive specifies the target node where initial
content will be loaded. If the path does not exist yet in the repository, it is created by
the content loader. The intermediate nodes are of type <tt>nt:folder</tt>. </td>
<td class='confluenceTd'> <tt>checkin</tt> </td>
<td class='confluenceTd'> <tt>checkin:=(true&#124;false)</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> The checkin directive specifies whether versionable nodes
should be checked in. </td>
<td class='confluenceTd'> <tt>ignoreImportProviders</tt> </td>
<td class='confluenceTd'> <tt>ignoreImportProviders:=list of extensions</tt>
<td class='confluenceTd'> <tt>empty</tt> </td>
<td class='confluenceTd'> This directive can be used to not run one of the configured
extractors (see below). </td>
<p>Examples of these directives uses could be (assumes a Sling-Initial-Content header
entry of SLING-INF/content):</p>
<table class='confluenceTable'><tbody>
<th class='confluenceTh'> Entry </th>
<th class='confluenceTh'> Behaviour </th>
<td class='confluenceTd'> <tt>SLING-INF/content/home;overwrite:=true;uninstall:=true</tt>
<td class='confluenceTd'> Overwrites already existing content in <em>/home</em>
and uninstalls the content when the bundle is unregistered. </td>
<td class='confluenceTd'> <tt>SLING-INF/content/home;path:=/sites/sling_website</tt>
<td class='confluenceTd'> if <em>/sites/sling_website</em> exists it loads
the content into it. Otherwise, it loads the content into root node <em>/</em>.
<td class='confluenceTd'> <tt>SLING-INF/content/home;checkin:=true</tt>
<td class='confluenceTd'> After content loading, versionable nodes are checked in. </td>

<h2><a name="ContentLoading-Loadinginitialcontentfrombundles"></a>Loading
initial content from bundles</h2>

<p>Repository items to be loaded into the repository, when the bundle is first installed,
may be defined in four ways:</p>
	<li>XML descriptor files</li>
	<li>JSON descriptor files</li>

<p>Depending on the bundle entry found in the location indicated by the Sling-Initial-Content
bundle manifest header, nodes are created (and/or updated) as follows:</p>

<h3><a name="ContentLoading-Directories"></a>Directories</h3>

<p>Unless a node with the name of the directory already exists or has been defined in
an XML or JSON descriptor file (see below) a directory is created as a node with the primary
node type "nt:folder" in the repository.</p>

<h3><a name="ContentLoading-Files"></a>Files</h3>

<p>Unless a node with the name of the file already exists or has been defined in an
XML or JSON descriptor file (see below) a file is created as two nodes in the repository.
The node bearing the name of the file itself is created with the<br/>
primary node type "nt:file". Underneath this file node, a resource node with the primary node
type "nt:resource" is created, which is set to the contents of the file.</p>

<p>The MIME type is derived from the file name extension by first trying to resolve
it from the Bundle entry URL. If this does not resolve to a MIME type, the Sling MIME type
resolution service is used to try to find a mime type. If all fals, the MIME type is defaulted
to "application/octet-stream".&nbsp;&nbsp;</p>

<h3><a name="ContentLoading-XMLDescriptorFiles"></a>XML Descriptor Files</h3>

<p>Nodes, Properties and in fact complete subtrees may be described in XML files using
either the JCR SystemView format, or the format described below. In either case, the file
must have the .xml extension.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;node&gt;</span>
			optional on top level, defaults to XML file name without .xml extension
	       	required for child nodes
		<span class="code-tag">&lt;name&gt;</span>xyz<span class="code-tag">&lt;/name&gt;</span>

	   		optional, defaults to nt:unstructured
		<span class="code-tag">&lt;primaryNodeType&gt;</span>nt:file<span

		    optional mixin node type
		    may be repeated for multiple mixin node types
		<span class="code-tag">&lt;mixinNodeType&gt;</span>mix:versionable<span
		<span class="code-tag">&lt;mixinNodeType&gt;</span>mix:lockable<span

			Optional properties for the node. Each <span class="code-tag">&lt;property&gt;</span>
element defines
			a single property of the node. The element may be repeated.
		<span class="code-tag">&lt;property&gt;</span>
				required property name
			<span class="code-tag">&lt;name&gt;</span>prop<span class="code-tag">&lt;/name&gt;</span>

				value of the property.
				For multi-value properties, the values are defined by multiple
				<span class="code-tag">&lt;value&gt;</span> elements nested inside
a <span class="code-tag">&lt;values&gt;</span> element instead of a
				single <span class="code-tag">&lt;value&gt;</span> element
			<span class="code-tag">&lt;value&gt;</span>property value as string<span

				Optional type of the property value, defaults to String.
				This must be one of the property type strings defined in the
				JCR PropertyType interface.
			<span class="code-tag">&lt;type&gt;</span>String<span class="code-tag">&lt;/type&gt;</span>
		<span class="code-tag">&lt;/property&gt;</span>

			Additional child nodes. May be further nested.
		<span class="code-tag">&lt;node&gt;</span>
		<span class="code-tag">&lt;/node&gt;</span>
	<span class="code-tag">&lt;/node&gt;</span>

<p>If you're including binary files (nt:file) in your content, you may store them anywhere,
and reference them from your XML by using nt:file elements. Use the &lt;nt:file&gt;
instead of a &lt;node&gt; where you want your file to appear in your repository content:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;nt:file src=<span class="code-quote">"url/relative/to/this/xml/image.jpg"</span>
mimeType=<span class="code-quote">"image/jpeg"</span> lastModified=<span class="code-quote">"2009-10-27'T'10:50:15+0100"</span>
<p>You may leave out the lastModified attribute - if so, the file's last modified date
as reported by the filesystem will be used.</p>

<h4><a name="ContentLoading-UsingacustomXMLformat"></a>Using a custom XML
<p>By writing an XSLT stylesheet file, you can use whatever XML format you prefer. The
XML file references an XSLT stylesheet by using the xml-stylesheet processing instruction:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;?xml version=<span class="code-quote">"1.0"</span>
encoding=<span class="code-quote">"UTF-8"</span>?&gt;</span>
<span class="code-tag">&lt;?xml-stylesheet href=<span class="code-quote">"my-transform.xsl"</span>
type=<span class="code-quote">"text/xsl"</span>?&gt;</span> <span
class="code-tag"><span class="code-comment">&lt;!-- The path to my-transform.xsl
is relative to this file --&gt;</span></span>

<span class="code-tag">&lt;your_custom_root_node&gt;</span>
   <span class="code-tag">&lt;your_custom_element&gt;</span>
   <span class="code-tag">&lt;/your_custom_element&gt;</span>
<span class="code-tag">&lt;/your_custom_root_node&gt;</span>

<p>The my-transform.xsl file is then responsible for translating your format into one
of the supported XML formats:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">

&lt;<span class="code-keyword">xsl:stylesheet</span> version=<span class="code-quote">"1.0"</span>
<span class="code-keyword">xmlns:jcr</span>=<span class="code-quote">""</span>
<span class="code-keyword">xmlns:mix</span>=<span class="code-quote">""</span>

  <span class="code-keyword">xmlns:sv</span>=<span class="code-quote">""</span>
<span class="code-keyword">xmlns:sling</span>=<span class="code-quote">""</span>
  <span class="code-keyword">xmlns:rep</span>=<span class="code-quote">"internal"</span>
<span class="code-keyword">xmlns:nt</span>=<span class="code-quote">""</span>
<span class="code-keyword">xmlns:xsl</span>=<span class="code-quote">""</span>&gt;

  <span class="code-tag">&lt;<span class="code-keyword">xsl:template</span>
match=<span class="code-quote">"your_custom_element"</span>&gt;</span>
    <span class="code-tag">&lt;node&gt;</span>
    <span class="code-tag">&lt;/node&gt;</span>
  <span class="code-tag">&lt;/<span class="code-keyword">xsl:template</span>&gt;</span>
<span class="code-tag">&lt;/<span class="code-keyword">xsl:stylesheet</span>&gt;</span>


<h3><a name="ContentLoading-JSONDescriptorFiles"></a>JSON Descriptor Files</h3>

<p>Nodes, Properties and in fact complete subtrees may be described in JSON files using
the following skeleton structure (see <a href="" rel="nofollow"></a>
or information on the syntax of JSON) :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
		<span class="code-comment">// optional node name on top level, <span class="code-keyword">default</span>
is file name without .json ext.
</span>		<span class="code-quote">"name"</span>: <span class="code-quote">"nodename"</span>,

		<span class="code-comment">// optional primary node type, <span class="code-keyword">default</span>
<span class="code-quote">"nt:unstructured"</span>
</span>		<span class="code-quote">"primaryNodeType"</span>: <span class="code-quote">"sling:ScriptedComponent"</span>,

		<span class="code-comment">// optional mixin node types as array
</span>		<span class="code-quote">"mixinNodeTypes"</span>: [ ],

	    <span class="code-comment">// the <span class="code-quote">"properties"</span>
property is an object indexed by property name whose
</span>	    <span class="code-comment">// value is either the string property
value, array <span class="code-keyword">for</span> multi-values or
</span>	    <span class="code-comment">// an object whose value[s] property denotes
the property value(s) and
</span>	    <span class="code-comment">// whose type property denotes the property
</span>	    <span class="code-quote">"properties"</span>: {
	    	<span class="code-quote">"sling:contentClass"</span>: <span class="code-quote">""</span>,
	    	<span class="code-quote">"sampleMulti"</span>: [ <span class="code-quote">"v1"</span>,
<span class="code-quote">"v2"</span> ],
	    	<span class="code-quote">"sampleStruct"</span>: {
	    		<span class="code-quote">"value"</span>: 1,
	    		<span class="code-quote">"type"</span>: <span class="code-quote">"<span
	    	<span class="code-quote">"sampleStructMulti"</span>: {
	    		<span class="code-quote">"value"</span>: [ 1, 2, 3 ],
	    		<span class="code-quote">"type"</span>: <span class="code-quote">"<span

	    <span class="code-comment">// the <span class="code-quote">"nodes"</span>
property is an array of objects denoting child nodes. Nodes
</span>	    <span class="code-comment">// may be further nested.
</span>		<span class="code-quote">"nodes"</span>: [
				<span class="code-comment">// the name property is required on (nested) child nodes
</span>	            <span class="code-quote">"name"</span>: <span class="code-quote">"sling:scripts"</span>,

				<span class="code-quote">"primaryNodeType"</span>: <span class="code-quote">"sling:ScriptList"</span>,

				<span class="code-quote">"nodes"</span>: [
						<span class="code-quote">"primaryNodeType"</span>: <span class="code-quote">"sling:Script"</span>,
						<span class="code-quote">"properties"</span>: {
							<span class="code-quote">"sling:name"</span>: <span class="code-quote">"/test/content/jsp/start.jsp"</span>,
							<span class="code-quote">"sling:type"</span>: <span class="code-quote">"jsp"</span>,
							<span class="code-quote">"sling:glob"</span>: <span class="code-quote">"*"</span>

<h3><a name="ContentLoading-Extractors"></a>Extractors</h3>

<p>By default, the <tt>sling-jcr-contentloader</tt> bundle tries to extract
certain file types during content loading. These include <tt>json</tt>, <tt>xml</tt>,
<tt>zip</tt>, and <tt>jar</tt> files. Therefore all available extractors
are used for content processing. However if some files should be put into the repository unextracted,
the <tt>ignoreImportProviders</tt> directive can be used with a comma separated
list of extensions that should not be extracted, like <tt>ignoreImportProviders:=jar,zip</tt>.</p>

<h2><a name="ContentLoading-DeclaredNodeTypeRegistration"></a>Declared Node
Type Registration</h2>

<p>The <tt>sling-jcr-base</tt> bundle provides low-level repository operations
which are at the heart of the functionality of Sling:</p>
	<li><b>Node Type Definitions</b> &#45; The class <tt></tt>
provides methods to register custom node types with a repository given a repository session
and a node type definition file in CND format. This class is also used by this bundle to register
node types on behalf of other bundles.</li>

<p>Bundles may list node type definition files in CND format in the <tt>Sling-Nodetypes</tt>
bundle header. This header is a comma-separated list of resources in the respective bundle.
Each resource is taken and fed to the <tt>NodeTypeLoader</tt> to define the node

<p>After a bundle has entered the <em>resolved</em> state, the node types
listed in the <tt>Sling-Nodetypes</tt> bundle header are registered with the repository.</p>

<p>Node types installed by this mechanism will never be removed again by the <tt>sling-jcr-base</tt>
bundle. Likewise, registered node types cannot currently be modified using this feature. The
<tt>NodeTypeLoader</tt> will try to load nodes defined and fail with a log message
if a node type has already been defined. To update existing node type definitions, native
repository functionality has to be used.</p>

<p>Nodetype management is currently a problematic issue, as the only API available is
contained in the Jackrabbit Core library, which is generally not available to client applications
- unless running in the same VM and class loader hierarchy as the Repository. Version 2 of
the JCR Specification currently being developped as JSR-283 should fix this issue by providing
an official node type management API. Until then, this approach is about the only solution
we have.</p>

<h3><a name="ContentLoading-Automatedtests"></a>Automated tests</h3>

<p>The initial content found in the <a href=""
rel="nofollow">sling-test folder of the launchpad initial content</a> is verified
by the <a href=""
rel="nofollow">InitialContentTest</a> when running the <em>launchpad/testing</em>
integration tests.</p>

<p>Those tests can be used as verified examples of initial content loading. Contributions
are welcome to improve the coverage of those tests.</p>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href=""
class="grey">Change Notification Preferences</a>

       <a href="">View
       <a href="">View
       <a href=";showCommentArea=true#addcomment">Add

View raw message