001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   https://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.commons.compress.archivers.zip;
020
021import java.util.zip.ZipException;
022
023/**
024 * Controls details of parsing ZIP extra fields.
025 *
026 * @since 1.19
027 */
028public interface ExtraFieldParsingBehavior extends UnparseableExtraFieldBehavior {
029
030    /**
031     * Creates an instance of ZipExtraField for the given id.
032     * <p>
033     * A good default implementation would be {@link ExtraFieldUtils#createExtraField}.
034     * </p>
035     *
036     * @param headerId the id for the extra field
037     * @return an instance of ZipExtraField, must not be {@code null}
038     * @throws ZipException           if an error occurs
039     * @throws InstantiationException if unable to instantiate the class, not thrown by Commons Compress.
040     * @throws IllegalAccessException if not allowed to instantiate the class, not thrown by Commons Compress.
041     */
042    ZipExtraField createExtraField(ZipShort headerId) throws ZipException, InstantiationException, IllegalAccessException;
043
044    /**
045     * Fills in the extra field data for a single extra field.
046     * <p>
047     * A good default implementation would be {@link ExtraFieldUtils#fillExtraField}.
048     * </p>
049     *
050     * @param field the extra field instance to fill
051     * @param data  the array of extra field data
052     * @param off   offset into data where this field's data starts
053     * @param len   the length of this field's data
054     * @param local whether the extra field data stems from the local file header. If this is false then the data is part if the central directory header extra
055     *              data.
056     * @return the filled field. Usually this is the same as {@code
057     * field} but it could be a replacement extra field as well. Must not be {@code null}.
058     * @throws ZipException if an error occurs
059     */
060    ZipExtraField fill(ZipExtraField field, byte[] data, int off, int len, boolean local) throws ZipException;
061}