svn commit: r1468889 - /felix/trunk/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java

[fm...@apache.org]

Author: fmeschbe
Date: Wed Apr 17 13:05:41 2013
New Revision: 1468889

URL: http://svn.apache.org/r1468889
Log:
Improve JavaDoc

Modified:
    felix/trunk/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java

Modified: felix/trunk/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java
URL: http://svn.apache.org/viewvc/felix/trunk/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java?rev=1468889&r1=1468888&r2=1468889&view=diff
==============================================================================
--- felix/trunk/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java (original)
+++ felix/trunk/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java Wed Apr 17 13:05:41 2013
@@ -6,9 +6,9 @@
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
- * 
+ *
  * http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -26,30 +26,36 @@ import java.util.zip.ZipOutputStream;
  * If a inventory printer implements this interface, the printer
  * can add additional attachments to the output of the
  * configuration ZIP.
- * 
- * A service implementing this method must still register itself
- * as a {@link InventoryPrinter} but not as a {@link ZipAttachmentProvider}
- * service and the provider
- * should either support {@link PrinterMode.ZIP_FILE_JSON} or
- * {@link PrinterMode.ZIP_FILE_TEXT}
+ * <p>
+ * A service implementing this method must register itself as a
+ * {@link InventoryPrinter} but not as a {@link ZipAttachmentProvider} service.
+ * When writing output to a ZIP file, this method is called if the
+ * {@link InventoryPrinter} service implements this interface.
  */
 public interface ZipAttachmentProvider
 {
 
     /**
-     * Add attachments to the zip output stream.
-     * The attachment provider can add as many attachments in any format
-     * as it wants. However it should use the namePrefix to create unique
-     * names / paths inside the zip.
-     * 
-     * The general pattern is: creating a zip entry by using the name prefix
-     * and a name, adding the entry to the zip output stream, writing
-     * the content of the file to the stream, and finally ending the
-     * zip entry.
-     * 
+     * Add attachments to the zip output stream. The attachment provider can add
+     * as many attachments in any format as it wants. However it should use the
+     * namePrefix to create unique names / paths inside the zip.
+     * <p>
+     * The general pattern is to do for each entry to be added:
+     * <ol>
+     * <li>Create ZipEntry with a name composed of {@code namePrefix} and a name
+     * unique to the attachement provider, e.g. {@code namePrefix + "att1.txt"}.
+     * </li>
+     * <li>Add the ZipEntry to the ZIP file {@code zos}.</li>
+     * <li>Write the contents of the entry; for example copying a filesystem
+     * file to the ZIP file {@code zos}.</li>
+     * <li>Close the ZipEntry.</li>
+     * </ol>
+     *
      * @param namePrefix Name prefix to use for zip entries. Ends with a slash.
      * @param zos The zip output stream.
-     * @throws IOException
+     * @throws IOException If an error occurrs writing the ZIP entry. This may
+     *             also be caused by reading some file system file to be added
+     *             to the ZIP file.
      */
     void addAttachments(final String namePrefix, final ZipOutputStream zos) throws IOException;
 }