001/*
002 *  jDTAUS Banking API
003 *  Copyright (C) 2005 Christian Schulte
004 *  <cs@schulte.it>
005 *
006 *  This library is free software; you can redistribute it and/or
007 *  modify it under the terms of the GNU Lesser General Public
008 *  License as published by the Free Software Foundation; either
009 *  version 2.1 of the License, or any later version.
010 *
011 *  This library is distributed in the hope that it will be useful,
012 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 *  Lesser General Public License for more details.
015 *
016 *  You should have received a copy of the GNU Lesser General Public
017 *  License along with this library; if not, write to the Free Software
018 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
019 *
020 */
021package org.jdtaus.banking;
022
023import java.util.Date;
024
025/**
026 * Public directory of german bank codes.
027 * <p>For further information see the
028 * <a href="../../../doc-files/merkblatt_bankleitzahlendatei.pdf">Merkblatt Bankleitzahlendatei</a>. An updated version of the document
029 * may be found at <a href="http://www.bundesbank.de">Deutsche Bundesbank</a>.</p>
030 * <p>Example: Getting the jDTAUS Banking SPI implementation.<br/><pre>
031 * BankleitzahlenVerzeichnis directory =
032 *     (BankleitzahlenVerzeichnis) ContainerFactory.getContainer().
033 *     getObject( BankleitzahlenVerzeichnis.class );
034 * </pre></p>
035 *
036 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
037 * @version $JDTAUS: BankleitzahlenVerzeichnis.java 8725 2012-10-04 21:26:50Z schulte $
038 *
039 * @see org.jdtaus.core.container.Container
040 */
041public interface BankleitzahlenVerzeichnis
042{
043
044    /**
045     * Gets the date of expiration of the data.
046     *
047     * @return the date of expiration of the data.
048     */
049    Date getDateOfExpiration();
050
051    /**
052     * Gets the record of the head office for a given Bankleitzahl.
053     *
054     * @param bankCode A Bankleitzahl to return the record of the corresponding head office for.
055     *
056     * @return The head office of the bank identified by {@code bankCode} or {@code null} if no head office exists for
057     * {@code bankCode}.
058     *
059     * @throws NullPointerException if {@code bankCode} is {@code null}.
060     * @throws BankleitzahlExpirationException if {@code bankCode} has expired.
061     */
062    BankleitzahlInfo getHeadOffice( Bankleitzahl bankCode ) throws BankleitzahlExpirationException;
063
064    /**
065     * Gets the records of the branch offices for a given Bankleitzahl.
066     *
067     * @param bankCode The Bankleitzahl to return the records of corresponding branch offices for.
068     *
069     * @return The branch offices of the bank identified by {@code bankCode} or an empty array if the directory does not
070     * hold corresponding records for {@code bankCode}.
071     *
072     * @throws NullPointerException if {@code bankCode} is {@code null}.
073     * @throws BankleitzahlExpirationException if {@code bankCode} has expired.
074     */
075    BankleitzahlInfo[] getBranchOffices( Bankleitzahl bankCode ) throws BankleitzahlExpirationException;
076
077    /**
078     * Searches the directory for records matching the given criteria.
079     *
080     * @param name Text to select records whose property {@code name} matches the given text; {@code null} to ignore
081     * property {@code name} in the search.
082     * @param postalCode Text to select records whose property {@code postalCode} matches the given text; {@code null}
083     * to ignore property {@code postalCode} in the search.
084     * @param city Text to select records whose property {@code city} matches the given text; {@code null} to ignore
085     * property {@code city} in the search.
086     * @param branchOffices {@code true} to return records for branch offices; {@code false} to return records for head
087     * offices.
088     *
089     * @return All records matching the given criteria.
090     *
091     * @throws IllegalArgumentException if {@code name}, {@code postalCode} or {@code city} contains data which cannot
092     * be used for searching the directory.
093     *
094     * @deprecated Replaced by {@link #searchBankleitzahlInfos(java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean, java.lang.Boolean)}.
095     */
096     BankleitzahlInfo[] search( String name, String postalCode, String city, boolean branchOffices );
097
098    /**
099     * Searches the directory for records matching the given criteria.
100     *
101     * @param name Text to select records whose property {@code name} matches the given text; {@code null} to ignore
102     * property {@code name} during searching.
103     * @param postalCode Text to select records whose property {@code postalCode} matches the given text; {@code null}
104     * to ignore property {@code postalCode} during searching.
105     * @param city Text to select records whose property {@code city} matches the given text; {@code null} to ignore
106     * property {@code city} during searching.
107     * @param headOffices {@code true} to return head office records; {@code false} to not return head office records;
108     * {@code null} to ignore property {@code headOffice} during searching.
109     * @param branchOffices {@code true} to return branch office records; {@code false} to not return branch office
110     * records; {@code null} to ignore property {@code headOffice} during searching.
111     *
112     * @return All records matching the given criteria.
113     *
114     * @throws IllegalArgumentException if {@code name}, {@code postalCode} or {@code city} contains data which cannot
115     * be used for searching the directory.
116     */
117    BankleitzahlInfo[] searchBankleitzahlInfos( String name, String postalCode, String city, Boolean headOffices,
118                                                Boolean branchOffices );
119
120}