001/*
002 * jPOS Project [http://jpos.org]
003 * Copyright (C) 2000-2026 jPOS Software SRL
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018
019package org.jpos.iso;
020
021import java.util.List;
022
023/**
024 * Represents one dataset instance inside an ISO 8583:2023 composite field.
025 */
026public interface Dataset {
027    /**
028     * Returns the dataset identifier as carried on the wire.
029     *
030     * @return dataset identifier in the range {@code 0x01} to {@code 0xFE}
031     */
032    int getIdentifier();
033
034    /**
035     * Returns the logical dataset encoding format.
036     *
037     * @return dataset format
038     */
039    DatasetFormat getFormat();
040
041    /**
042     * Returns all decoded elements in insertion order.
043     *
044     * @return immutable list of dataset elements
045     */
046    List<DatasetElement> getElements();
047
048    /**
049     * Returns all elements that match the supplied element identifier.
050     *
051     * @param id element identifier, either a TLV tag or DBM bit number
052     * @return immutable list of matching elements
053     */
054    List<DatasetElement> getElements(int id);
055
056    /**
057     * Returns the first element that matches the supplied identifier.
058     *
059     * @param id element identifier, either a TLV tag or DBM bit number
060     * @return matching element or {@code null} when absent
061     */
062    DatasetElement getElement(int id);
063}