package com.intershop.component.address.capi;

/**
 * The interface describes an address in the business objects level.
 */
public interface AddressBO extends BusinessObject
{
    /**
     * Returns the reference used to uniquely identify the {@link AddressBO}. The ID
     *  has the following structure:
     * </p>
     * {@code AddressID@AddressType:AddressOwnerID}
     * </p>
     * <ul>
     * <li><b>AddressID</b> - The UUID of the address.</li>
     * <li><b>AddressType</b> - The domain object that owns the address.</li>
     * <li><b>AddressOwnerID</b> - The UUID of the domain object instance that
     * owns the address.</li>
     * </ul>
     *
     * @return the unique address reference.
     */
    String getAddressReference();

    /**
     * Returns the name of the address.
     *
     * @return the name of the address or <code>null</code> if not specified.
     */
    String getAddressName();

    /**
     * Returns an {@link java.util.EnumSet} containing the types of usage.
     * Following types of usage are defined:
     * <ul>
     * <li><b>Usage.InvoiceTo</b> - The invoice-to address.</li>
     * <li><b>Usage.ShipTo</b> - The ship-to address.</li>
     * <li><b>Usage.ShipFrom</b> - The ship-from address.</li>
     * <li><b>Usage.ServiceTo</b> - The service-to address.</li>
     * <li><b>Usage.InstallTo</b> - The install-to address.</li>
     * </ul>
     *
     * @return an {@link java.util.EnumSet} containing the types of usage.
     */
    EnumSet<Usage> getUsage();

    /**
     * Returns the honorific title
     *
     * @return the honorific title
     */
    String getHonorific();

    /**
     * Returns the title
     *
     * @return the title
     */
    String getTitle();

    /**
     * Returns the first name
     *
     * @return the first name
     */
    String getFirstName();

    /**
     * Returns the second name.
     *
     * @return the second name.
     */
    String getSecondName();

    /**
     * Returns the last name.
     *
     * @return the last name.
     */
    String getLastName();

    /**
     * Returns the second last name.
     *
     * @return the second last name.
     */
    String getSecondLastName();

    /**
     * Returns the first address line.
     *
     * @return the first address line.
     */
    String getAddressLine1();

    /**
     * Returns the second address line. This line is optional if room is needed
     * to include more identifying information than a simple street and house
     * number, e.g.:
     * </p>
     * <i>Address Line 1: Northern University</br>
     * Address Line 2: 1111 Main Street</i>
     *
     * @return the second address line or <code>null</code> if not specified.
     */
    String getAddressLine2();

    /**
     * Returns the third address line. This line is optional if room is needed
     * to include more identifying information than a simple street and house
     * number.
     *
     * @return the third address line or <code>null</code> if not specified.
     */
    String getAddressLine3();

    /**
     * Returns the city.
     *
     * @return the city.
     */
    String getCity();

    /**
     * Returns the postal code
     *
     * @return the postal code
     */
    String getPostalCode();

    /**
     * Returns the display name of the country in the current locale.
     *
     * @return the display name of the country.
     */
    String getCountry();

    /**
     * Returns the ISO 3166-1 country code.
     *
     * @return the ISO 3166-1 country code.
     */
    String getCountryCode();

    /**
     * Returns the main division of the country, e.g., a state
     * or province.
     *
     * @return the main division of the country or <code>null</code>
     * if not specified.
     */
    String getMainDivision();

    /**
     * Returns the sub division of the main division, e.g., a county
     * or prefecture.
     *
     * @return the sub division or <code>null</code> if not specified.
     */
    String getSubDivision();

    /**
     * Returns the post box
     *
     * @return the post box
     */
    String getPostBox();

    /**
     * Returns the home phone
     *
     * @return  the home phone
     */
    String getPhoneHome();

    /**
     * Returns the mobile phone
     *
     * @return  the mobile phone
     */
    String getPhoneMobile();

    /**
     * Returns the business phone
     *
     * @return the business phone
     */
    String getPhoneBusiness();

    /**
     * Returns the direct business phone
     *
     * @return the direct business phone
     */
    String getPhoneBusinessDirect();

    /**
     * Returns the fax of the address.
     *
     * @return the fax of the address.
     */
    String getFax();

    /**
     * Returns the email address
     *
     * @return the email address
     */
    String getEMail();

    /**
     * Returns the company name
     *
     * @return the company name
     */
    String getCompanyName1();

    /**
     * Returns the second company name
     *
     * @return the second company name
     */
    String getCompanyName2();
}

package com.intershop.component.address.capi;

/**
 * The interface describes an address in the business objects level.
 */
public interface AddressBOUpdateAddressExtension extends BusinessObjectExtension<AddressBO>
{
    /**
     * Sets the name of the address.
     *
     * @param name the name of the address.
     */
    void setAddressName(String addressName);

    /**
     * Sets the types of usage by the specified {@link java.util.EnumSet}.
     * Following types of usage are defined:
     * <ul>
     * <li><b>Usage.InvoiceTo</b> - The invoice-to address.</li>
     * <li><b>Usage.ShipTo</b> - The ship-to address.</li>
     * <li><b>Usage.ShipFrom</b> - The ship-from address.</li>
     * <li><b>Usage.ServiceTo</b> - The service-to address.</li>
     * <li><b>Usage.InstallTo</b> - The install-to address.</li>
     * </ul>
     *
     * @param usage the {@link java.util.EnumSet} containing the types
     * of usage.
     */
    void getUsage(EnumSet<Usage> usage);

    /**
     * Sets the honorific title
     *
     * @param honorific the honorific title
     */
    void setHonorific(String honorific);

    /**
     * Sets the title
     *
     * @param title the title
     */
    void setTitle(String title);

    /**
     * Sets the first name.
     *
     * @param firstName the first name.
     */
    void setFirstName(String firstName);

    /**
     * Sets the second name
     *
     * @param secondName the second name
     */
    void setSecondName(String secondName);

    /**
     * Sets the last name.
     *
     * @param lastName the last name.
     */
    void setLastName(String lastName);

    /**
     * Sets the second last name.
     *
     * @param secondLastName the last name.
     */
    void setSecondLastName(String secondLastName);

    /**
     * Sets the first address line. Note that first address line is mandatory.
     *
     * @param addressLine1 the first address line.
     */
    void setAddressLine1(String addressLine1);

    /**
     * Sets the second address line.
     *
     * @param addressLine2 the second address line.
     */
    void setAddressLine2(String addressLine2);

    /**
     * Sets the third address line.
     *
     * @param addressLine3 the third address line.
     */
    void setAddressLine3(String addressLine3);

    /**
     * Sets the city.
     *
     * @param city the city.
     */
    void setCity(String city);

    /**
     * Returns the postal code
     *
     * @param postalCode the postal code
     */
    void setPostalCode(String postalCode);

    /**
     * Sets the ISO 3166-1 country code.
     *
     * @param countryCode the ISO 3166-1 country code.
     */
    void setCountryCode(String countryCode);

    /**
     * Sets the the main division of the country.
     *
     * @param mainDivision the main division
     */
    void setMainDivision(String mainDivision);

    /**
     * Sets the the sub division of the country.
     *
     * @param subDivision the sub division
     */
    void setSubDivision(String subDivision);

    /**
     * Sets the post box.
     *
     * @param postBox the post box.
     */
    void setPostBox(String postBox);

    /**
     * Sets the home phone
     *
     * @param phoneHome the home phone
     */
    void setPhoneHome(String phoneHome);

    /**
     * Sets the mobile phone
     *
     * @param phoneMobile the mobile phone
     */
    void setPhoneMobile(String phoneMobile);

    /**
     * Sets the business phone
     *
     * @param phoneBusiness the business phone
     */
    void setPhoneBusiness(String phoneBusiness);

    /**
     * Sets the direct business phone
     *
     * @param phoneBusinessDirect the direct business phone
     */
    void setPhoneBusinessDirect(String phoneBusinessDirect);

    /**
     * Sets the fax of the address.
     *
     * @param the fax of the address.
     */
    void setFax(String fax);

    /**
     * Sets the email address
     *
     * @param eMail the email address
     */
    void setEMail(String eMail);

    /**
     * Sets the company name
     *
     * @param companyName the company name
     */
    void setCompanyName(String companyName);

    /**
     * Sets the second company name
     *
     * @param companyName the second company name
     */
    void setCompanyName2(String companyName);
}

package com.intershop.component.address.capi.resolver;

import com.intershop.component.address.capi.AddressBO;

/**
 * Interface for resolving {@link AddressBO} objects from address URNs. Resolvers are registered via Java extension
 * point "com.intershop.component.address.capi.resolver.AddressBOResolver-AddressResolving".
 */
public interface AddressBOResolver
{
    /**
     * Resolves an address from the given URN.
     * 
     * @param urn
     *            URN to resolve address from
     * @return Address or <code>null</code> if not found
     */
    AddressBO resolve(String urn);

    /**
     * Checks if this resolver supports the given URN notation. This method is used for looking up the correct resolver
     * for a given URN. Note that a positive result doesn't necessarily mean that this resolver will also find a result
     * for the given URN; it only states that the syntax of the URN can be parsed by the resolver.
     * 
     * @param urn
     *            URN to resolve address from
     * @return <code>true</code> if this resolver supports the given URN notation; else <code>false</code>
     */
    boolean supports(String urn);
}