com.aspose.words
Interface IMailMergeDataSource


public interface IMailMergeDataSource 

Implement this interface to allow mail merge from a custom data source, such as list of objects.

Example:

Performs mail merge from a custom data source.
public void mailMergeCustomDataSource() throws Exception
{
    // Create some data that we will use in the mail merge.
    CustomerList customers = new CustomerList();
    customers.add(new Customer("Thomas Hardy", "120 Hanover Sq., London"));
    customers.add(new Customer("Paolo Accorti", "Via Monte Bianco 34, Torino"));

    // Open the template document.
    Document doc = new Document(getMyDir() + "MailMerge.CustomDataSource.doc");

    // To be able to mail merge from your own data source, it must be wrapped
    // into an object that implements the IMailMergeDataSource interface.
    CustomerMailMergeDataSource customersDataSource = new CustomerMailMergeDataSource(customers);

    // Now you can pass your data source into Aspose.Words.
    doc.getMailMerge().execute(customersDataSource);

    doc.save(getMyDir() + "MailMerge.CustomDataSource Out.doc");
}

/// <summary>
/// An example of a "data entity" class in your application.
/// </summary>
public class Customer
{
    public Customer(String fullName, String address)
    {
        mFullName = fullName;
        mAddress = address;
    }

    public String getFullName()
    {
        return mFullName;
    }
    public void setFullName(String value)
    {
        mFullName = value;
    }

    public String getAddress()
    {
        return mAddress;
    }
    public void setAddress(String value)
    {
        mAddress = value;
    }

    private String mFullName;
    private String mAddress;
}

/// <summary>
/// An example of a typed collection that contains your "data" objects.
/// </summary>
public class CustomerList extends ArrayList<Customer>

{
    public Customer get(int index)
    {
        return super.get(index);
    }

    public Customer set(int index, Customer element)
    {
        return super.set(index, element);
    }
}

/// <summary>
/// A custom mail merge data source that you implement to allow Aspose.Words
/// to mail merge data from your Customer objects into Microsoft Word documents.
/// </summary>
public class CustomerMailMergeDataSource implements IMailMergeDataSource
{
    public CustomerMailMergeDataSource(CustomerList customers)
    {
        mCustomers = customers;

        // When the data source is initialized, it must be positioned before the first record.
        mRecordIndex= -1;
    }

    /// <summary>
    /// The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
    /// </summary>
    public String getTableName()
    {
        return "Customer";
    }

    /// <summary>
    /// Aspose.Words call this to get a value for every data field.
    /// </summary>
    public boolean getValue(String fieldName,  Object[] fieldValue)
    {
        if ("FullName".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getFullName();
            return true;
        }
        else if("Address".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getAddress();
            return true;
        }
        else
        {
            // A field with this name was not found,
            // return false to the Aspose.Words mail merge engine.
            fieldValue[0] = null;
            return false;
        }
    }

    /// <summary>
    /// A standard implementation for moving to a next record in a collection.
    /// </summary>
    public boolean moveNext()
    {
        if (isEof())
            return false;

        mRecordIndex++;

        return (!isEof());
    }

    private boolean isEof()
    {
        return (mRecordIndex >= mCustomers.size());
    }

    private CustomerList mCustomers;
    private int mRecordIndex;
}
See Also:
MailMerge

Property Getters/Setters Summary
abstract java.lang.StringgetTableName()
           Returns the name of the data source.
 
Method Summary
abstract booleangetValue(java.lang.String fieldName, java.lang.Object[] fieldValue)
           Returns a value for the specified field name or false if the field is not found.
abstract booleanmoveNext()
           Advances to the next record in the data source.
 

Property Getters/Setters Detail

getTableName

public abstract java.lang.String getTableName()
Returns the name of the data source.

If you are implementing IMailMergeDataSource, return the name of the data source from this property.

Aspose.Words uses this name to match against the mail merge region name specified in the template document. The comparison between the data source name and the mail merge region name is not case sensitive.

Example:

Performs mail merge from a custom data source.
public void mailMergeCustomDataSource() throws Exception
{
    // Create some data that we will use in the mail merge.
    CustomerList customers = new CustomerList();
    customers.add(new Customer("Thomas Hardy", "120 Hanover Sq., London"));
    customers.add(new Customer("Paolo Accorti", "Via Monte Bianco 34, Torino"));

    // Open the template document.
    Document doc = new Document(getMyDir() + "MailMerge.CustomDataSource.doc");

    // To be able to mail merge from your own data source, it must be wrapped
    // into an object that implements the IMailMergeDataSource interface.
    CustomerMailMergeDataSource customersDataSource = new CustomerMailMergeDataSource(customers);

    // Now you can pass your data source into Aspose.Words.
    doc.getMailMerge().execute(customersDataSource);

    doc.save(getMyDir() + "MailMerge.CustomDataSource Out.doc");
}

/// <summary>
/// An example of a "data entity" class in your application.
/// </summary>
public class Customer
{
    public Customer(String fullName, String address)
    {
        mFullName = fullName;
        mAddress = address;
    }

    public String getFullName()
    {
        return mFullName;
    }
    public void setFullName(String value)
    {
        mFullName = value;
    }

    public String getAddress()
    {
        return mAddress;
    }
    public void setAddress(String value)
    {
        mAddress = value;
    }

    private String mFullName;
    private String mAddress;
}

/// <summary>
/// An example of a typed collection that contains your "data" objects.
/// </summary>
public class CustomerList extends ArrayList<Customer>

{
    public Customer get(int index)
    {
        return super.get(index);
    }

    public Customer set(int index, Customer element)
    {
        return super.set(index, element);
    }
}

/// <summary>
/// A custom mail merge data source that you implement to allow Aspose.Words
/// to mail merge data from your Customer objects into Microsoft Word documents.
/// </summary>
public class CustomerMailMergeDataSource implements IMailMergeDataSource
{
    public CustomerMailMergeDataSource(CustomerList customers)
    {
        mCustomers = customers;

        // When the data source is initialized, it must be positioned before the first record.
        mRecordIndex= -1;
    }

    /// <summary>
    /// The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
    /// </summary>
    public String getTableName()
    {
        return "Customer";
    }

    /// <summary>
    /// Aspose.Words call this to get a value for every data field.
    /// </summary>
    public boolean getValue(String fieldName,  Object[] fieldValue)
    {
        if ("FullName".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getFullName();
            return true;
        }
        else if("Address".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getAddress();
            return true;
        }
        else
        {
            // A field with this name was not found,
            // return false to the Aspose.Words mail merge engine.
            fieldValue[0] = null;
            return false;
        }
    }

    /// <summary>
    /// A standard implementation for moving to a next record in a collection.
    /// </summary>
    public boolean moveNext()
    {
        if (isEof())
            return false;

        mRecordIndex++;

        return (!isEof());
    }

    private boolean isEof()
    {
        return (mRecordIndex >= mCustomers.size());
    }

    private CustomerList mCustomers;
    private int mRecordIndex;
}
Returns:
The name of the data source. Empty string if the data source has no name.

Method Detail

moveNext

public abstract boolean moveNext()
                              throws java.lang.Exception
Advances to the next record in the data source.
Returns:
True if moved to next record successfully. False if reached end of the data source.

Example:

Performs mail merge from a custom data source.
public void mailMergeCustomDataSource() throws Exception
{
    // Create some data that we will use in the mail merge.
    CustomerList customers = new CustomerList();
    customers.add(new Customer("Thomas Hardy", "120 Hanover Sq., London"));
    customers.add(new Customer("Paolo Accorti", "Via Monte Bianco 34, Torino"));

    // Open the template document.
    Document doc = new Document(getMyDir() + "MailMerge.CustomDataSource.doc");

    // To be able to mail merge from your own data source, it must be wrapped
    // into an object that implements the IMailMergeDataSource interface.
    CustomerMailMergeDataSource customersDataSource = new CustomerMailMergeDataSource(customers);

    // Now you can pass your data source into Aspose.Words.
    doc.getMailMerge().execute(customersDataSource);

    doc.save(getMyDir() + "MailMerge.CustomDataSource Out.doc");
}

/// <summary>
/// An example of a "data entity" class in your application.
/// </summary>
public class Customer
{
    public Customer(String fullName, String address)
    {
        mFullName = fullName;
        mAddress = address;
    }

    public String getFullName()
    {
        return mFullName;
    }
    public void setFullName(String value)
    {
        mFullName = value;
    }

    public String getAddress()
    {
        return mAddress;
    }
    public void setAddress(String value)
    {
        mAddress = value;
    }

    private String mFullName;
    private String mAddress;
}

/// <summary>
/// An example of a typed collection that contains your "data" objects.
/// </summary>
public class CustomerList extends ArrayList<Customer>

{
    public Customer get(int index)
    {
        return super.get(index);
    }

    public Customer set(int index, Customer element)
    {
        return super.set(index, element);
    }
}

/// <summary>
/// A custom mail merge data source that you implement to allow Aspose.Words
/// to mail merge data from your Customer objects into Microsoft Word documents.
/// </summary>
public class CustomerMailMergeDataSource implements IMailMergeDataSource
{
    public CustomerMailMergeDataSource(CustomerList customers)
    {
        mCustomers = customers;

        // When the data source is initialized, it must be positioned before the first record.
        mRecordIndex= -1;
    }

    /// <summary>
    /// The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
    /// </summary>
    public String getTableName()
    {
        return "Customer";
    }

    /// <summary>
    /// Aspose.Words call this to get a value for every data field.
    /// </summary>
    public boolean getValue(String fieldName,  Object[] fieldValue)
    {
        if ("FullName".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getFullName();
            return true;
        }
        else if("Address".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getAddress();
            return true;
        }
        else
        {
            // A field with this name was not found,
            // return false to the Aspose.Words mail merge engine.
            fieldValue[0] = null;
            return false;
        }
    }

    /// <summary>
    /// A standard implementation for moving to a next record in a collection.
    /// </summary>
    public boolean moveNext()
    {
        if (isEof())
            return false;

        mRecordIndex++;

        return (!isEof());
    }

    private boolean isEof()
    {
        return (mRecordIndex >= mCustomers.size());
    }

    private CustomerList mCustomers;
    private int mRecordIndex;
}

getValue

public abstract boolean getValue(java.lang.String fieldName, java.lang.Object[] fieldValue)
                              throws java.lang.Exception
Returns a value for the specified field name or false if the field is not found.

The fieldValue parameter emulates .NET out parameter.

Before calling this method you should initialize the fieldValue parameter to {null}. After this method returns true, you can get the value from fieldValue[0].
            Object[] fieldValue = {null};
            boolean isValueFound = mDataSource.getValue(fieldName, fieldValue);
            int value = isValueFound ? fieldValue[0] : 0;
            

If you implement this method, then when the requested field is found, you should assign the value fieldValue[0] and return true.

Parameters:
fieldName - The name of the data field.
fieldValue - Returns the field value.
Returns:
True if value was found.

Example:

Performs mail merge from a custom data source.
public void mailMergeCustomDataSource() throws Exception
{
    // Create some data that we will use in the mail merge.
    CustomerList customers = new CustomerList();
    customers.add(new Customer("Thomas Hardy", "120 Hanover Sq., London"));
    customers.add(new Customer("Paolo Accorti", "Via Monte Bianco 34, Torino"));

    // Open the template document.
    Document doc = new Document(getMyDir() + "MailMerge.CustomDataSource.doc");

    // To be able to mail merge from your own data source, it must be wrapped
    // into an object that implements the IMailMergeDataSource interface.
    CustomerMailMergeDataSource customersDataSource = new CustomerMailMergeDataSource(customers);

    // Now you can pass your data source into Aspose.Words.
    doc.getMailMerge().execute(customersDataSource);

    doc.save(getMyDir() + "MailMerge.CustomDataSource Out.doc");
}

/// <summary>
/// An example of a "data entity" class in your application.
/// </summary>
public class Customer
{
    public Customer(String fullName, String address)
    {
        mFullName = fullName;
        mAddress = address;
    }

    public String getFullName()
    {
        return mFullName;
    }
    public void setFullName(String value)
    {
        mFullName = value;
    }

    public String getAddress()
    {
        return mAddress;
    }
    public void setAddress(String value)
    {
        mAddress = value;
    }

    private String mFullName;
    private String mAddress;
}

/// <summary>
/// An example of a typed collection that contains your "data" objects.
/// </summary>
public class CustomerList extends ArrayList<Customer>

{
    public Customer get(int index)
    {
        return super.get(index);
    }

    public Customer set(int index, Customer element)
    {
        return super.set(index, element);
    }
}

/// <summary>
/// A custom mail merge data source that you implement to allow Aspose.Words
/// to mail merge data from your Customer objects into Microsoft Word documents.
/// </summary>
public class CustomerMailMergeDataSource implements IMailMergeDataSource
{
    public CustomerMailMergeDataSource(CustomerList customers)
    {
        mCustomers = customers;

        // When the data source is initialized, it must be positioned before the first record.
        mRecordIndex= -1;
    }

    /// <summary>
    /// The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
    /// </summary>
    public String getTableName()
    {
        return "Customer";
    }

    /// <summary>
    /// Aspose.Words call this to get a value for every data field.
    /// </summary>
    public boolean getValue(String fieldName,  Object[] fieldValue)
    {
        if ("FullName".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getFullName();
            return true;
        }
        else if("Address".equals(fieldName))
        {
            fieldValue[0] = mCustomers.get(mRecordIndex).getAddress();
            return true;
        }
        else
        {
            // A field with this name was not found,
            // return false to the Aspose.Words mail merge engine.
            fieldValue[0] = null;
            return false;
        }
    }

    /// <summary>
    /// A standard implementation for moving to a next record in a collection.
    /// </summary>
    public boolean moveNext()
    {
        if (isEof())
            return false;

        mRecordIndex++;

        return (!isEof());
    }

    private boolean isEof()
    {
        return (mRecordIndex >= mCustomers.size());
    }

    private CustomerList mCustomers;
    private int mRecordIndex;
}

See Also:
          Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
          Aspose.Words Support Forum - our preferred method of support.