    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}