Document Properties
Kbid28U055
Last Modified16-Jul-2020
Added to KB07-Nov-2016
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Address Handling

1 Introduction

This concept is addressed to developers and consultants who want to use or enhance the address handling. With growing B2B focus requirements for addresses have changed. Therefore Intershop introduced a new approach.

Additionally we should consider previously made mistakes that caused several escalations. The former address handling is confusing and error-prone for the following reasons:

Database Layer

Structure on the database layer reflects the requirements from more than a decade ago. There are the following tables containing address related data:

  • BASICADDRESS - Stores addresses of users (customers) and organizations.
  • STATICADDRESS - Stores addresses assigned to the orders and addresses created in the course of unregistered checkouts.
  • STORE - Stores addresses of retail stores.

The structure above does not support scenarios where other domain objects need to deal with address data too, neither in the context of the IS7 standard product (e.g., customer, channel) nor in customer projects (e.g., warehouse, etc.). Using the BASICADDRESS table for such purposes fails on the foreign key constraint to the BASICPROFILE table.

Business Object Layer

The Business Object layer currently represents address data by the com.intershop.component.address.capi.AddressBO interface. Any functionality that deals with instances of AddressBO is not aware of the origin of the address data, means the owner of this data. This behavior causes problems, because the functionality cannot determine, whether the data of the AddressBO can be manipulated or not.

Application Layer (UI/REST)

Problems described for Business Object Layer becomes even more problematic on the Application Layer. Functionality on this layer commonly deals with lists of addresses from different sources. Simple requirements, like choosing an arbitrary addresses from the list and changing them result in complex functionality.

1.1 References

2 Address Owners

Following domain objects require possibility to own address data:
Domain ObjectDescriptionRelationship Domain Object : Address
(Channel)Address of the subsidiary of the organization. Some customers structure their Web shop by mapping subsidiaries in a specific country to an ICM channel. In the North American region the address of a subsidiary is required for taxation.1 : 1
(Department)Address of a department1 : 1
BasketAddresses created by unregistered users in the course of an unregistered checkout1 : n
CustomerAddresses of a B2B customers1 : n
OrderAddresses created once during fulfillment of an order and never changed afterwards1 : n
OrganizationAddress of the organization that offers goods via the Web shop1 : 1
StoreAddresses of retail stores1 : 1
UserAddresses of a users1 : n

2.1 Persistence Layer

In the face of the number of different domain objects specifying their own address data and the requirements of projects to easily introduce new project specific domain objects that may be address owners too, it appears likely to provide support by the JGEN code generation tool. One approach would be that a domain object could simply specify, that each row in domain object's database table has a relationship to one or multiple addresses belonging to this object, same way like already done for AttributeValues of ExtensibleObject(s).
Unfortunately the grammar of JGEN EDL is derived by Java, that does not allow multiple class inheritance to express this. Furthermore EDL does not support declaration of any aspects in the context of a domain object at all. So address tables and relationships to domain objects have to be designed manually.

Nevertheless each domain object should define a separate database table that stores the addresses this object owns:

Persistent (Domain) ObjectPersistent Address ObjectAddress TablePreviously stored in TableSupported
CRUD operations
OrganizationPOOrganizationAddressPOORGANIZATIONADDRESSBASICADDRESSCRUD
UserPOUserAddressPOUSERADDRESS CRUD
CustomerPOCustomerAddressPOCUSTOMERADDRESSBASICADDRESSCRUD
StorePOStoreAddressPOSTOREADDRESSSTORECRUD
BasketPOBasketAddressPOBASKETADDRESSBASICADDRESS/STATICADDRESSCRUD
OrderPOOrderAddressPOORDERADDRESSSTATICADDRESSCR

2.2 Database Schema

Address tables in the database should have a uniform structure. There are the following changes in contrast to the previous BASICADDRESS and STATICADDRESS tables:

  • Main- and subdivisions of countries are stored in two generic columns instead of defining country specific columns for each.
  • Transcription columns are not supported any longer.
  • Columns related to the contact person's name support global naming conventions now.

Database schema of the address tables has the following structure now:

Column NameTypeMandatoryDescription
{FOREIGN KEY to TABLE of Address Owner}VARCHAR2(28 CHAR)XAddress owner's UUID
ADDRESSNAMEVARCHAR2(256 CHAR) The name of the address
USAGENUMBER(11,0) Describes the usage of the address.
ARISTOCRATICTITLEVARCHAR2(40 CHAR) The title of the contact person, that is an aristocratic title, like Lord or Lady , in the most cases

HONORIFIC

VARCHAR2(256 CHAR) The honorific title of the contact person, that denotes the honored person's occupation, like Captain, Coach, Officer, Reverend or the academic title, like PhD
TITLEVARCHAR2(256 CHAR) The personal title, like Ms. , Mr. 

FIRSTNAME

VARCHAR2(256 CHAR) The given name (also known as a personal name, first name, forename, or Christian name) of the contact person
SECONDNAMEVARCHAR2(256 CHAR) The second given name of the contact person. Allocation depends on the culture area, in European countries this would be regarded as the second name, whereas in United States a person has usually one middle name.

LASTNAME

VARCHAR2(256 CHAR) The surname (also known as a family name, last name, or gentile name) of the contact person
SECONDLASTNAMEVARCHAR2(256 CHAR) The second last name of the contact person. Allocation depends on the culture area, second last (sur-) name is common in Hispanic culture.
ADDRESSLINE1VARCHAR2(256 CHAR) The first address line, that usual contains street and house number
ADDRESSLINE2VARCHAR2(256 CHAR) 

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.:

Address Line 1: Northern University
Address Line 2: 1111 Main Street

ADDRESSLINE3VARCHAR2(256 CHAR) 

The third address line. This line is optional if room is needed to include additional information, e.g., apartment or building.

POSTBOX

VARCHAR2(256 CHAR) 

The post office box (commonly referred to as a PO box or a postal box)

A box with a number in a post office to which your letters and parcels can be sent and from which you can pick them up.

CITYVARCHAR2(256 CHAR) The name of the local authority district (city, village, hamlet)
POSTALCODEVARCHAR2(256 CHAR) The code of letters and digits used as part of a postal address to aid the sorting of mail. Also called (in Britain and certain other countries) postcode US equivalent zip code
COUNTRYCODEVARCHAR2(3 CHAR) The ISO 3166 country code (ALPHA-2 or ALPHA-3)
MAINDIVISIONVARCHAR2(256 CHAR) 

The main division of the country, e.g., state or province

SUBDIVISIONVARCHAR2(256 CHAR) 

The sub division of the main division, e.g., county or prefecture

PHONEHOMEVARCHAR2(256 CHAR) The phone number of the house or apartment where the contact person lives
PHONEMOBILEVARCHAR2(256 CHAR) The number of contact person's cell phone
PHONEBUSINESSVARCHAR2(256 CHAR) The number of contact person's company
PHONEBUSINESSDIRECTVARCHAR2(256 CHAR)  Business phone number extension that allows an outside caller to connect directly to the contact person without any help of an attendant or operator.
FAXVARCHAR2(256 CHAR) The number of contact persons for facsimile machine
EMAILVARCHAR2(256 CHAR) Contact person's e-mail account
JOBTITLEVARCHAR2(256 CHAR) The job title of the contact person. By correctly addressing the job title of the recipient, you can ensure that it gets to the right person, especially in large companies that they may have more than one person with the same name.
COMPANYNAME1VARCHAR2(256 CHAR) The company name
COMPANYNAME2VARCHAR2(256 CHAR) This line is optional if room is needed to include more information of the company.
DOMAINIDVARCHAR2(28 CHAR)XSystem column
UUIDVARCHAR2(28 CHAR)XThe UUID of the address entry in the database
OCANUMBER(11,0)XSystem column
LASTMODIFIEDTIMESTAMP(9)XSystem column

2.2.1 Intended Future Changes

Future releases of the Intershop Commerce Management may introduce several new address attributes. Intershop has not yet introduced these data base columns because there were currently not needed and we did not want to fill the data base with fields that are possibly not used. Nevertheless, if a sufficient number of customers and/or partners consider this useful, Intershop may introduce these address attributes with a future release. Until then, projects should stick to the column names and data types here to ease future migration.

Column nameTypeMandatoryDescription
LONGITUDENUMBER(11,8) 

Geographical longitude of the address

LATITUDENUMBER(10,8) 

Geographical latitude of the address

EXTERNALADDRESSIDVARCHAR2(256 CHAR) 

The ID an address has in an external system, e.g., CRM or ERP system

2.2.2 Address Usage

In real scenarios an address might be limited to special types of usage. So a specific address might only represent a shipping target, whereas another address should only be used to send invoices to that. Types of usage are represented by bit codes on the database layer. On the Business Object Layer the usage is defined by a Java enum type. Multiple types of usage are formed by java.util.EnumSet. 

Following bit codes are supported by default:

Bit CodeMeaning
(1 =) 0000 0001invoice-to address
(2 =) 0000 0010ship-to address
(4 =) 0000 0100ship-from address
(8 =) 0000 1000service-to address
(16 =) 0001 0000install-to address

Furthermore any combinations of above's bit codes are allowed, e.g.:

Bit CodeMeaning
(5 =) 0000 0101invoice-to and ship-from address
(11 =) 0000 1011invoice-to, ship-to and service-to address

Note

There is a clear separation between address usage and address type now. Mixing both concepts, like done in former Enfinity Suite 6.x and Intershop 7.x versions are due to a insufficient architecture. The concept of a store address is realized by defining the domain object Store. Now this object can be the owner of an address.

2.3 Business Object Layer

The Business Object layer has to provide functionality for CRUD (Create/Retrieve/Update/Delete) operations on addresses in the context the owning domain object. For this purpose the domain object owning addresses has to implement the com.intershop.component.address.capi.AddressBORepository interface that defines operations for creation, retrieval and deletion of address:

concept_address_handling_address_bo_repository Copy

3 Address References

There are domain objects that deal with address data owned by other objects. The basket is a typical example for that, whereas a basket can refer to addresses owned by other domain objects, as well as have its own addresses, e.g., a ship-to address in the course of an unregistered checkout.
Domain ObjectReferencesDescription
BasketUser, Customer, Store, external systems 

An address assigned to the basket cannot be resolved by only specifying the address ID, because of the fact, that the logic responsible for address resolution requires some context, e.g., the domain object instance that is owning the address with the specified ID. Following information have to be provided to resolve an address owned by a domain object in the Intershop Commerce Management:

  • Address ID - The UUID of the address
  • Address Type - The domain object that owns the address
  • Address Owner ID - The UUID of the domain object instance that owns the address

3.1 Persistence Layer

On the database layer address references are stored in URN notation:

concept_address_handling_address_reference

Note

This pattern is only for default ICM addresses. There might also be references to addresses stored in external systems, especially in B2B scenarios. A custom URN namespace and pattern can be used in such case.

3.2 Business Object Layer

concept_address_handling_addressbo_and_extensions

3.2.1 AddressBO

In contrast to former implementation of the AddressBO interface there are the following differences:

  • The interface does not define any setter-methods for address data updates, but getter-methods only. All setter methods are marked as to be deprecated and implementations use the AddressBOUpdateAddressExtension to change data or throw a java.lang.IllegalStateException as result of a call in case no such extension is present for the given AddressBO.
  • Generic support for sub and main divisions of a country has been introduced by the two methods AddressBO::getMainDivision() and AddressBO::getSubDivision() now. Previous methods for access to specific main and subdivisions, like state, province, county, prefecture, etc., are marked as to be deprecated and mapped to the generic methods like following:
    • AddressBO::getState()      -> AddressBO::getMainDivision()

    • AddressBO::getProvince()   -> AddressBO::getMainDivision()
    • AddressBO::getCounty()     -> AddressBO::getSubDivision()

    • AddressBO::getPrefecture() -> AddressBO::getSubDivision()

    • AddressBO::getRegion()     -> AddressBO::getSubDivision()

AddressBO
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();
}

3.2.2 Usage

The AddressBO#getUsage() field is a java.util.BitSet where every bit denotes another address capability. Further bits may be introduced in custom projects to allow for more usage capabilities. The default usages and associated bits in the set can be found in the table below.

BitUsage Type
0Invoice-to address
1Ship-to address
2Ship-from address
3Service-to address
4Install-to address

3.2.3 AddressBOUpdateAddressExtension

All methods providing update functionality for address data have been moved from the AddressBO to the AddressBOUpdateAddressExtension interface. This is because any functionality that has access to an instance of AddressBO in the program flow might not be aware, whether data of this address can be modified in the current context or not:

  • AddressBO instance represents an address of another address owner, e.g., an address owned by the domain object Customer is set as invoice-to address at the basket. It is not permitted to change data of this address during checkout.
  • New permission concept is introduced, which controls access to specific business objects.

Defining setter-methods for address data updates in the AddressBO interface would imply, that every call of such a method would finish in a java.lang.UnsupportedOperationException or java.lang.IllegalStateException if changes are not permitted for this instance. By moving setter-methods to the AddressBOUpdateAddressExtension any functionality dealing with addresses may check, if this extension is applicable to a specific AddressBO instance. This makes it easier, e.g., in ObjectPath, to check whether a user is allowed to edit an address (if not the extension would not be returned).

AddressBOUpdateAddressExtension
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);
}

3.2.4 Address Resolution

Address resolution has to be extensible to fit the needs of customer projects that may introduce additional domain objects that own addresses, e.g., warehouse, repair shop, etc. .

AddressBOResolver
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);
}

4 Address Preferences

Users may define a preferred invoice-to and ship-to address. This can be an address of an arbitrary address owner, like a user, a customer, a store or by any other address owner:

Assignment of preferred invoice-to and ship-to address are integral part of customer and user (profile) data. Therefore two address references have to be stored for the customer and user. Because customer and user data are stored in table BASICPROFILE following columns have been added to this table:

Column NameTypeMandatoryDescription
PREFERREDINVOICETOADDRESSURNVARCHAR2(256 CHAR) The address reference to the preferred invoice-to address of the customer/user
PREFERREDSHIPTOADDRESSURNVARCHAR2(256 CHAR) The address reference to the preferred ship-to address of the customer/user

5 Extension Points

Several extension points are available which allow to plugin custom code:

Extension PointTypeUsed inDescription
Default Extensions
com.intershop.component.address.capi.handler.AddressCreationHandler-CustomerAddressCreatingJava

com.intershop.component.customer.orm.internal.ORMCustomerBOImpl.createAddressBO(AddressBO)

com.intershop.component.customer.orm.internal.ORMCustomerBOImpl.createAddressBO()

com.intershop.component.customer.orm.internal.ORMCustomerBOImpl.createAddressBO(String) (deprecated)

(cartridge "bc_customer_orm")

The extension point is executed before a customer address is created. If an error is returned by any registered extension, the address creation will be cancelled and subsequent handlers will not be executed.
  • com.intershop.component.address.capi.handler.impl.PreventDuplicateAddressesHandler

Prevents the creation of addresses which have the same address data as already existing addresses. Returns failure code "DuplicateAddress" if such an address is about to be created. Also returns the existing address so it can be used afterwards.

com.intershop.component.address.capi.handler.AddressCreationHandler-BasketAddressCreatingJava

com.intershop.component.basket.orm.internal.BasketBOImpl.createAddressBO(AddressBO)

com.intershop.component.basket.orm.internal.BasketBOImpl.createAddressBO()

com.intershop.component.basket.orm.internal.BasketBOImpl.createAddressBO(String) (deprecated)

(cartridge "bc_basket_orm")

The extension point is executed before a basket address is created. If an error is returned by any registered extension, the address creation will be cancelled and subsequent handlers will not be executed.
  • com.intershop.component.address.capi.handler.impl.PreventDuplicateAddressesHandler

Prevents the creation of addresses which have the same address data as already existing addresses. Returns failure code "DuplicateAddress" if such an address is about to be created. Also returns the existing address so it can be used afterwards.

com.intershop.component.address.capi.handler.AddressDeletionHandler-CustomerAddressDeleting

Java

com.intershop.component.customer.orm.internal.ORMCustomerBOImpl.deleteAddressBO(AddressBO)

(cartridge "bc_customer_orm")

The extension point is executed before a customer address is deleted. If an error is returned by any registered extension, the address deletion will be cancelled and subsequent handlers will not be executed.
  • com.intershop.component.customer.orm.internal.orm.handlers.ForbidLastAddressDeletionHandler

Prevents the deletion of the last customer address. Returns failure code "LastAddress" if the last address is about to be deleted.

com.intershop.component.address.capi.handler.AddressDeletionHandler-BasketAddressDeletingJava

com.intershop.component.basket.orm.internal.BasketBOImpl.deleteAddressBO(AddressBO)

(cartridge "bc_basket_orm")

The extension point is executed before a basket address is deleted. If an error is returned by any registered extension, the address deletion will be cancelled and subsequent handlers will not be executed.(none)
com.intershop.component.address.capi.handler.AddressUpdateHandler-AddressUpdatingJava

com.intershop.component.address.orm.internal.ORMAddressBOUpdateExtensionImpl.copyDataFromAddress(AddressBO)

(and in all setter methods)

(cartridge "bc_address_orm")

The extension point is executed before an address is updated. If an error is returned by any registered extension, the address will not be updated and subsequent handlers will not be executed.

Note that this only applies to AddressBO implementations that inherit from com.intershop.component.address.orm.capi.AbstractORMAddressBOImpl.

  • com.intershop.component.address.capi.handler.impl.PreventDuplicateAddressesHandler

Prevents the creation of addresses which have the same address data as already existing addresses. Returns failure code "DuplicateAddress" if an address is about to be updated with address data from an already existing address.

com.intershop.component.address.capi.handler.CopyAddressDataHandler-CopyAddressDataJava

com.intershop.component.address.orm.internal.ORMAddressBOUpdateExtensionImpl.copyDataFromAddress(AddressBO)

(cartridge "bc_address_orm")

The extension point is executed after an address has been updated by copying all address data from another address. Handlers may copy additional data that are not covered by the default setter methods.

Note that this only applies to AddressBO implementations that inherit from com.intershop.component.address.orm.capi.AbstractORMAddressBOImpl.

  • com.intershop.component.address.orm.internal.CopyCustomAttributesHandlerImpl

Copies all custom attributes if both addresses internally reference an extensible object.

com.intershop.component.address.capi.handler.CompareAddressDataHandler-CompareAddressDataJava

com.intershop.component.address.orm.capi.AbstractORMAddressBOImpl.hasSameAddressData(AddressBO)

(cartridge "bc_address_orm")

The extension point is executed whenever two addresses are compared via method com.intershop.component.address.capi.AddressBO.hasSameAddressData(AddressBO). Handlers may plugin here to compare additional attributes that are not covered via the default getter methods.

Note that this only applies to AddressBO implementations that inherit from com.intershop.component.address.orm.capi.AbstractORMAddressBOImpl.

(none)
com.intershop.component.address.capi.resolver.AddressBOResolver-AddressResolvingJava

com.intershop.component.address.internal.resolver.CompositeAddressBOResolverImpl.resolve(String)

com.intershop.component.address.internal.resolver.CompositeAddressBOResolverImpl.supports(String)

(cartridge "bc_address")

The extension point is executed whenever an address URN is to be resolved.

Also see Recipe: Implement a Custom Address Resolver in the Cookbook - Address Handling.

  • com.intershop.component.basket.internal.BasketAddressBOResolverImpl

Resolves basket addresses.

  • com.intershop.component.customer.internal.CustomerAddressBOResolverImpl

Resolves customer addresses.

  • com.intershop.component.orderprocess.internal.UUIDAddressBOResolverImpl

Resolves address UUIDs. This resolver only exists for compatibility reasons and will be removed in a future release.

com.intershop.component.basket.capi.BasketAddressHandler-BasketAddressHandlingJava

com.intershop.component.basket.internal.BasketAddressHandlerImpl.isValidInvoiceToAddressBO(BasketBO, AddressBO)

com.intershop.component.basket.internal.BasketAddressHandlerImpl.isValidShipToAddressBO(BasketBO, AddressBO)

com.intershop.component.basket.internal.BasketAddressHandlerImpl.isValidShipFromAddressBO(BasketBO, AddressBO)

(cartridge "bc_basket")

The extension point is executed whenever an address is set as invoice-to, ship-to or ship-from address at a given basket or line item. The handler determines if the given address is allowed to be set. An address is eligible if at least one handler allows it. By default, only basket addresses or addresses of the basket's owning user (resp. customer) are permitted.

Also see Cookbook - Address Handling.

  • com.intershop.component.orderprocess.internal.StoreBasketAddressHandlerImpl

Allows stores to be set as invoice-to, ship-to or ship-from addresses.

6 Address ImpEx

The schema for the address import was adjusted for the new address handling. Until further notice, the "old" schema is still supported for import.

The export works with the new elements only.

Element NameComment
address-name
address-nrdeprecated, will be removed
city
country-code
countydeprecated, will be removed, use sub-division instead
postbox
postal-code
prefecturedeprecated, will be removed, use sub-division instead
provincedeprecated, will be removed, use main-division instead
regiondeprecated, will be removed
statedeprecated, will be removed, use main-division instead
sub-divisionnew
main-divisionnew
street-transcriptiondeprecated, will be removed
homepagedeprecated, will be removed
mobiledeprecated, will be removed, use phone-mobile instead
phone-mobilenew
phone-home
phone-business
phone-business-direct
company-namedeprecated, will be removed, use company-name1 instead
company-name1new
company-name2
company-name-transcriptiondeprecated, will be removed
honorific
aristocratic-titlenew
title
job-title
suffixdeprecated, will be removed
first-name-transcriptiondeprecated, will be removed
last-name
last-name-transcriptiondeprecated, will be removed
first-name
second-name
second-name-transcriptiondeprecated, will be removed
second-lastname
streetdeprecated, will be removed, use address-line1 instead
street2deprecated, will be removed, use address-line2 instead
street3deprecated, will be removed, use address-line3 instead
address-line1new
address-line2new
address-line3new
email
fax

7 Migration


See Guide - 7.8 Migration Addresses for details.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets