File and Archive Uploads
------------------------

When a new file or archive (eg. .zip file) is uploaded, the 
nuxeo-dam/nuxeo-dam-core/src/main/java/org/nuxeo/dam/core/listener/InitPropertiesListener.java 
event listener class is triggered.

1. Composite Files
------------------

If a composite file is being uploaded (ie. an archive like a zip), the
method is called repeatedly for:

i.  first the import set (which is considered to be the archive as a whole)
ii. every level of folder/file in the archive

For ImportSets and Folders, no action is taken. For documents which aren't
ImportSets or Folders, the document is tagged with the same attribute values
that were given to the root ImportSet on the upload screen by the user.

For example for the following archive, called images.zip with the following contents:

images/
|-- Folder1
|   |-- Folder1a
|   |   |-- fitheight.png
|   |   |-- gimp-rotate-180.png
|   |   `-- gimp-rotate-270.png
|   |-- fitbest.png
|   `-- gimp-flip-vertical.png
|-- Folder2
|-- Folder3
|   `-- Folder3a
|       `-- gimp-rotate-90.png
|-- Folder4
|   `-- Folder4a
|-- double-page.png
|-- fitmanual.png
|-- fitwidth.png
|-- gimp-flip-horizontal.png
|-- gimp-thumbnails.png
|-- library.png
|-- manga.png
|-- tango-add-bookmark.png
|-- tango-archive.png
`-- tango-image.png

Is uploaded with the following details put into the upload screen:

-----------------
Title: Images.With.Multiple Folder Levels
Description: Images with multiple folder levels test
Author of assets: Multiple Folder Author
Authoring date of assets: 10/15/09
Coverage: Europe
          Guernsey
Expiration date: 10/30/09
-----------------


the sequence of processing in InitPropertiesListener.java is:

Start...
Document type: [ImportSet]
Document name: [images-with-multiple]

Start...
Document type: [Folder]
Document name: [images]

Start...
Document type: [Folder]
Document name: [folder1]

Start...
Document type: [Folder]
Document name: [folder1a]

* Start...
* Document type: [Picture]
* Document name: [fitheight]

* Start...
* Document type: [Picture]
* Document name: [gimp-rotate-180]

etc etc

and the result in the repository is:

127.0.0.1> pwd
/default-domain/import-sets/images-with-multiple/images
127.0.0.1> cd folder1/folder1a
127.0.0.1> ls
fitheight
gimp-rotate-180
gimp-rotate-270
3 docs listed in 19ms
127.0.0.1>

When viewed on the selection screen, a sample image within the archive
would be seen to have the same attributes as the parent ImportSet (see above),
barring the Title attribute which is unique to the image. 
For eg.
----------------------------
Title: gimp-flip-vertical
Description: Images with multiple folder levels test
Author of assets: Multiple Folder Author
Authoring date of assets: 10/15/09
Coverage: Europe
          Guernsey
Expiration date: 10/30/09
----------------------------

2. Single Files
---------------

Single files are also treated as import sets with containing a single
document.

If a single file is being uploaded (eg. amami islands.jpg), the
method is called repeatedly for:

i.  first the import set (which is considered to be the archive as a whole)
ii. every level of folder/file in the archive

Say it is uploaded with the following details put into the upload screen:

-----------------
Title: IMPORT SINGLE
Description: IMPORT SINGLE DESC
Author of assets: SINGLE AUTHOR
Authoring date of assets: 10/9/09
Coverage: Antarctica
          South Georgia and the South Sandwich Islands
Expiration date: 10/28/09
-----------------

the sequence of processing in InitPropertiesListener.java is:

Start...
Document type: [ImportSet]
Document name: [import-single]

* Start...
* Document type: [Picture]
* Document name: [amami-islands]

And in the repository the structure is:

127.0.0.1> pwd  
/default-domain/import-sets/import-single
127.0.0.1> ls
amami-islands
1 docs listed in 21ms
127.0.0.1> 

where 'amami-islands' is the Picture document.















