Changeset 3762

Timestamp:

Sep 21, 2007, 9:18:07 AM (16 years ago)

Author:

Nicklas Nordborg

Message:

References #554, #746 and fixes #411. File and directories diagram transfered to new MagicDraw? and
docbook. Added documentation about compression support.

Location:

trunk/doc/src/docbook

Files:

• developerdoc/api_overview.xml (modified) (1 diff)
• figures/uml/datalayer.files.png (added)

trunk/doc/src/docbook/developerdoc/api_overview.xml

@@ -649 +649 @@
     <sect2 id="data_api.files">
       <title>Files and directories</title>
+
+      <para>
+        This section covers the details of the BASE file
+        system.
+      </para>
+
+      <sect3 id="data_api.files.uml">
+      <title>UML diagram</title>
+      
+        <figure id="data_api.figures.files">
+          <title>Files and directories</title>
+          <screenshot>
+            <mediaobject>
+              <imageobject>
+                <imagedata 
+                  fileref="figures/uml/datalayer.files.png" format="PNG" />
+              </imageobject>
+            </mediaobject>
+          </screenshot>
+        </figure>
+      </sect3>
+      
+      <sect3 id="data_api.files.description">
+        <title>Description</title>
+        
+        <para>
+          The <classname>DirectoryData</classname> class holds
+          information about directories. Directories are organised in the
+          ususal way as as tree structure. All directories must have
+          a parent directory, except the system-defined root directory.
+        </para>
+        
+        <para>
+          The <classname>FileData</classname> class holds information about
+          a file. The actual file contents is stored on disk in the directory
+          specified by the <varname>userfiles</varname> setting in 
+          <filename>base.config</filename>. The <varname>internalName</varname>
+          property is the name of the file on disk, but this is never exposed to 
+          client applications. The filenames and directories
+          on the disk doesn't correspond to the the filenames and directories in 
+          BASE.
+        </para>
+        
+        <para>
+          The <varname>location</varname> property can take three values:
+        </para>
+        
+        <itemizedlist>
+        <listitem>
+          <para>
+          0 = The file is offline, ie. there is no file on the disk
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          1 = The file is in primary storage, ie. it is located on the disk
+          and can be used by BASE
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          2 = The file is in secondary storage, ie. it has been moved to some
+          other place and can't be used by BASE immediately.
+          </para>
+        </listitem>
+        </itemizedlist>
+        
+        <para>
+          The <varname>action</varname> property controls how a file is
+          moved between primary and seconday storage. It can have the following
+          values:
+        </para>
+        
+        <itemizedlist>
+        <listitem>
+          <para>
+          0 = Do nothing
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          1 = If the file is in secondary storage, move it back to the primary storage
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          2 = If the file is in primary storage, move it to the secondary storage
+          </para>
+        </listitem>
+        </itemizedlist>
+        
+        <para>
+          The actual moving between primary and secondary storage is done by an 
+          external program. See 
+          <xref linkend="appendix.base.config.secondary" /> and 
+          <xref linkend="plugin_developer.other.secondary" /> for more information.
+        </para>
+      
+        <para>
+          The <varname>md5</varname> property can be used to check for file
+          corruption when it is moved between primary and secondary storage or
+          when a user re-uploads a file that has been offline.
+        </para>
+        
+        <para>
+          BASE can store files in a compressed format. This is handled internally
+          and is not visible to client applications. The <varname>compressed</varname>
+          and <varname>diskSize</varname> properties are used to store information
+          about this. A file may always be compressed if the users says so, but
+          BASE can also do this automatically if the file is uploaded
+          to a directory with the <varname>autoCompress</varname> flag set
+          or if the file has MIME type with the <varname>autoCompress</varname>
+          flag set.
+        </para>
+        
+        <para>
+          The <classname>FileTypeData</classname> class holds information about 
+          file types. It is used only to make it easier for users to organise 
+          their files.
+        </para>
+        
+        <para>
+          The <classname>MimeTypeData</classname> is used to register mime types and
+          map them to file extensions. The information is only used to lookup values 
+          when needed. Given the filename we can set the <varname>File.mimeType</varname>
+          and <varname>File.fileType</varname> properties. The MIME type is also
+          used to decide if a file should be stored in a compressed format or not.
+          The extension of a MIME type must be unique. Extensions should be registered 
+          without a dot, ie <emphasis>html</emphasis>, not <emphasis>.html</emphasis>.  
+        </para>
+        
+      </sect3>
+      
+      
     </sect2>