<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"	[
<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
%CustomDTD;
]>
<chapter id="zip-file-sequencer">
  <title>ZIP File Sequencer</title>
    <para>
    	The ZIP file sequencer is included in ModeShape and extracts the files and folders contained in the ZIP archive file,
		extracting the files and folders into the repository using JCR's <code>nt:file</code> and <code>nt:folder</code> 
		built-in node types.  The structure of the output thus matches the logical structure of the contents of the ZIP file.
    </para>
  
      <sect1>
        <title>Example</title>
	    <para>This sequencer generates a graph structure that maps to the files and folders in the ZIP file.  An example  
	    (listed in the JCR document view) from sequencing a ZIP file written into /a/foo and containing one file, /x/y/z.txt
	    is provided below:
	    </para>
	    <programlisting language="XML" role="XML"><![CDATA[
<foo jcr:primaryType="zip:file"
     jcr:mixinTypes="mode:derived"
     mode:derivedAt="2011-05-13T13:12:03.925Z"
     mode:derivedFrom="/files/docForReferenceGuide.xml" >
  <x jcr:primaryType="nt:folder" 
     jcr:created="2011-05-12T20:07Z"
     jcr:createdBy="currentJcrUser">
    <y jcr:primaryType="nt:folder" 
       jcr:created="2011-05-12T20:09Z"
       jcr:createdBy="currentJcrUser">
      <z.txt jcr:primaryType="nt:file">
        <jcr:content jcr:primaryType="nt:resource"
                     jcr:data="This is the file content"
                     jcr:lastModified="2011-05-12T20:12Z"
                     jcr:lastModifiedBy="currentJcrUser" 
                     jcr:mimeType="text/plain" />
      </z.txt>
    </y>
  </x>         
</foo>
]]></programlisting>
    <para>
       The CND for the zip:file node type is listed below.
    </para>
    <programlisting><![CDATA[
[zip:file] > nt:folder, mix:mimeType    
]]></programlisting>
	<para>
		To use this sequencer, simply include the <code>modeshape-sequencer-zip</code> JAR
		in your application and configure the &JcrConfiguration; to use this sequencer using something similar to:
	   </para>
   <programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...

config.sequencer("ZIP Sequencer")
      .usingClass("org.modeshape.sequencer.zip.ZipSequencer")
      .loadedFromClasspath()
      .setDescription("Sequences compressed files to extract the internal file and folder structure")
      .sequencingFrom("//(*.(zip|gz|jar|war|ear)[*])/jcr:content[@jcr:data]")
      .andOutputtingTo("/zips/$1");	
]]></programlisting>
  </sect1>
</chapter>
