Improve JavaDoc
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1468889 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java b/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java
index 7fb53df..00f0b77 100644
--- a/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java
+++ b/inventory/src/main/java/org/apache/felix/inventory/ZipAttachmentProvider.java
@@ -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 @@
* 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;
}