001/*
002 * Shredzone Commons - pdb
003 *
004 * Copyright (C) 2009 Richard "Shred" Körber
005 *   http://commons.shredzone.org
006 *
007 * This program is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU Library General Public License as
009 * published by the Free Software Foundation, either version 3 of the
010 * License, or (at your option) any later version.
011 *
012 * This program is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU Library General Public License
018 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
019 */
020package org.shredzone.commons.pdb.converter;
021
022import java.io.IOException;
023
024import org.shredzone.commons.pdb.PdbDatabase;
025import org.shredzone.commons.pdb.PdbFile;
026import org.shredzone.commons.pdb.appinfo.AppInfo;
027import org.shredzone.commons.pdb.record.Record;
028
029/**
030 * Converts a PDB record into an {@link Record} object.
031 */
032public interface Converter <T extends Record, U extends AppInfo> {
033
034    /**
035     * Checks if this record converter is able to convert records for the PdbDatabase.
036     *
037     * @param database
038     *            The {@link PdbDatabase} that is currently generated. Note that the
039     *            database is still being read. The basic attributes are already read and
040     *            may be used, but the appinfo and records are still incomplete. You would
041     *            usually access the database to read the database name or creator.
042     * @return {@code true} if the converter is able to process the database records.
043     */
044    boolean isAcceptable(PdbDatabase<T, U> database);
045
046    /**
047     * Converts raw record data to a {@link Record} object.
048     *
049     * @param reader
050     *            {@link PdbFile} with the file cursor at the beginning of the record
051     * @param record
052     *            Record number that is currently read
053     * @param size
054     *            Size of this record, in bytes
055     * @param attribute
056     *            Attributes of this record (unsigned byte)
057     * @param database
058     *            The {@link PdbDatabase} that is currently generated. Note that the
059     *            database is still being read. The attributes and appinfo are already
060     *            read and may be used, but the records are still incomplete. You would
061     *            usually access the database to read the database name or the category
062     *            map.
063     * @return {@link Record} object containing the data of this record, or {@code null}
064     *         if the raw data did not result in a record (e.g. because it was deleted).
065     */
066    T convert(PdbFile reader, int record, int size, int attribute, PdbDatabase<T, U> database)
067        throws IOException;
068
069    /**
070     * Converts raw application info data to an {@link AppInfo}.
071     *
072     * @param reader
073     *            {@link PdbFile} with the file cursor at the beginning of the appinfo
074     *            area
075     * @param size
076     *            Estimated size of the appinfo area, in bytes. Note that the actual
077     *            appinfo area might be smaller.
078     * @param database
079     *            The {@link PdbDatabase} that is currently generated. Note that the
080     *            database is still being read. The simple attributes are already read
081     *            and may be used, but the appinfo and records are still empty. Usually
082     *            you would like to ignore this parameter if possible.
083     * @return {@link AppInfo} object containing the converted appinfo
084     */
085    U convertAppInfo(PdbFile reader, int size, PdbDatabase<T, U> database)
086        throws IOException;
087
088}