/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * 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
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.felix.inventory;

import java.io.IOException;
import java.util.zip.ZipOutputStream;

/**
 * This is an optional extension of the {@link InventoryPrinter}.
 * 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}
 */
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.
     * 
     * @param namePrefix Name prefix to use for zip entries. Ends with a slash.
     * @param zos The zip output stream.
     * @throws IOException
     */
    void addAttachments(final String namePrefix, final ZipOutputStream zos) throws IOException;
}

@@ -417,17 +417,16 @@
 se at%0A *
- 
 %0A * http
@@ -466,17 +466,16 @@
 E-2.0%0A *
- 
 %0A * Unle
@@ -1114,16 +1114,19 @@
 ZIP.%0A * 
+%3Cp%3E
 %0A * A se
@@ -1165,14 +1165,8 @@
 ust 
-still 
 regi
@@ -1180,16 +1180,16 @@
 self
-%0A *
  as a
+%0A *
  %7B@l
@@ -1256,19 +1256,16 @@
 der%7D
-%0A *
  service
  and
@@ -1264,124 +1264,139 @@
 vice
- and the provider%0A * should either support %7B@link PrinterMode.ZIP_FILE_JSON%7D or%0A * %7B@link PrinterMode.ZIP_FILE_TEXT%7D
+.%0A * When writing output to a ZIP file, this method is called if the%0A * %7B@link InventoryPrinter%7D service implements this interface.
 %0A */
@@ -1494,23 +1494,16 @@
  stream.
-%0A     *
  The att
@@ -1526,16 +1526,23 @@
  can add
+%0A     *
  as many
@@ -1567,23 +1567,16 @@
 y format
-%0A     *
  as it w
@@ -1602,24 +1602,31 @@
 ould use the
+%0A     *
  namePrefix 
@@ -1641,23 +1641,16 @@
 e unique
-%0A     *
  names /
@@ -1671,32 +1671,35 @@
 the zip.%0A     * 
+%3Cp%3E
 %0A     * The gene
@@ -1716,87 +1716,253 @@
 n is
-: creating a zip entry by using the name prefix%0A     * and a name, adding
+ to do for each entry to be added:%0A     * %3Col%3E%0A     * %3Cli%3ECreate ZipEntry with a name composed of %7B@code namePrefix%7D and a name%0A     * unique to the attachement provider, e.g. %7B@code namePrefix + %22att1.txt%22%7D.%0A     * %3C/li%3E%0A     * %3Cli%3EAdd
  the 
-e
+ZipE
 ntry
@@ -1973,41 +1973,51 @@
 the 
-zip output stream, writing%0A     *
+ZIP file %7B@code zos%7D.%3C/li%3E%0A     * %3Cli%3EWrite
  the
@@ -2024,24 +2024,25 @@
  content
+s
  of the 
 file to 
@@ -2037,76 +2037,149 @@
 the 
-file to the stream, and finally ending the%0A     * zip entry.%0A     * 
+entry; for example copying a filesystem%0A     * file to the ZIP file %7B@code zos%7D.%3C/li%3E%0A     * %3Cli%3EClose the ZipEntry.%3C/li%3E%0A     * %3C/ol%3E%0A     *
 %0A   
@@ -2322,16 +2322,183 @@
 xception
+ If an error occurrs writing the ZIP entry. This may%0A     *             also be caused by reading some file system file to be added%0A     *             to the ZIP file.
 %0A     */

Improve JavaDoc