public interface IMailMergeDataSource
When a data source is created, it should be initialized to point to BOF (before the first record).
The Aspose.Words mail merge engine will invoke Example:
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");
}
/**
* An example of a "data entity" class in your application.
*/
public class Customer
{
public Customer(String aFullName, String anAddress) throws Exception
{
mFullName = aFullName;
mAddress = anAddress;
}
public String getFullName() throws Exception { return mFullName; }
public void setFullName(String value) throws Exception { mFullName = value; }
public String getAddress() throws Exception { return mAddress; }
public void setAddress(String value) throws Exception { mAddress = value; }
private String mFullName;
private String mAddress;
}
/**
* An example of a typed collection that contains your "data" objects.
*/
public class CustomerList extends ArrayList
{
public Customer get(int index) { return (Customer)super.get(index); }
public void set(int index, Customer value) { super.set(index, value); }
}
/**
* 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.
*/
public class CustomerMailMergeDataSource implements IMailMergeDataSource
{
public CustomerMailMergeDataSource(CustomerList customers) throws Exception
{
mCustomers = customers;
// When the data source is initialized, it must be positioned before the first record.
mRecordIndex= -1;
}
/**
* The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions.
*/
public String getTableName() throws Exception { return "Customer"; }
/**
* Aspose.Words calls this method to get a value for every data field.
*/
public boolean getValue(String fieldName, Object[] fieldValue) throws Exception
{
if (fieldName.equals("FullName"))
{
fieldValue[0] = mCustomers.get(mRecordIndex).getFullName();
return true;
}
else if (fieldName.equals("Address"))
{
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;
}
}
/**
* A standard implementation for moving to a next record in a collection.
*/
public boolean moveNext() throws Exception
{
if (!isEof())
mRecordIndex++;
return (!isEof());
}
public IMailMergeDataSource getChildDataSource(String tableName) throws Exception
{
return null;
}
private boolean isEof() throws Exception { return (mRecordIndex >= mCustomers.size()); }
private final CustomerList mCustomers;
private int mRecordIndex;
}
Property Getters/Setters Summary | ||
---|---|---|
abstract java.lang.String | getTableName() | |
Returns the name of the data source. |
Method Summary | ||
---|---|---|
abstract IMailMergeDataSource | getChildDataSource(java.lang.String tableName) | |
The Aspose.Words mail merge engine invokes this method when it encounters a beginning of a nested mail merge region. | ||
abstract boolean | getValue(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 boolean | moveNext() | |
Advances to the next record in the data source. |
Property Getters/Setters Detail |
---|
getTableName | |
public abstract java.lang.String getTableName() |
If you are implementing
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"); } /** * An example of a "data entity" class in your application. */ public class Customer { public Customer(String aFullName, String anAddress) throws Exception { mFullName = aFullName; mAddress = anAddress; } public String getFullName() throws Exception { return mFullName; } public void setFullName(String value) throws Exception { mFullName = value; } public String getAddress() throws Exception { return mAddress; } public void setAddress(String value) throws Exception { mAddress = value; } private String mFullName; private String mAddress; } /** * An example of a typed collection that contains your "data" objects. */ public class CustomerList extends ArrayList { public Customer get(int index) { return (Customer)super.get(index); } public void set(int index, Customer value) { super.set(index, value); } } /** * 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. */ public class CustomerMailMergeDataSource implements IMailMergeDataSource { public CustomerMailMergeDataSource(CustomerList customers) throws Exception { mCustomers = customers; // When the data source is initialized, it must be positioned before the first record. mRecordIndex= -1; } /** * The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions. */ public String getTableName() throws Exception { return "Customer"; } /** * Aspose.Words calls this method to get a value for every data field. */ public boolean getValue(String fieldName, Object[] fieldValue) throws Exception { if (fieldName.equals("FullName")) { fieldValue[0] = mCustomers.get(mRecordIndex).getFullName(); return true; } else if (fieldName.equals("Address")) { 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; } } /** * A standard implementation for moving to a next record in a collection. */ public boolean moveNext() throws Exception { if (!isEof()) mRecordIndex++; return (!isEof()); } public IMailMergeDataSource getChildDataSource(String tableName) throws Exception { return null; } private boolean isEof() throws Exception { return (mRecordIndex >= mCustomers.size()); } private final CustomerList mCustomers; private int mRecordIndex; }
Method Detail |
---|
getChildDataSource | |
public abstract IMailMergeDataSource getChildDataSource(java.lang.String tableName) throws java.lang.Exception |
When the Aspose.Words mail merge engines populates a mail merge region with data and encounters the beginning of a nested
mail merge region in the form of MERGEFIELD TableStart:TableName, it invokes
Below are the rules that the implementation of
If the table that is represented by this data source object has a related child (detail) table with the specified name,
then your implementation needs to return a new
If this data source object does not have a relation to the table with the specified name, then you need to return
a
If a table with the specified name does not exist, your implementation should return null
.
tableName
- The name of the mail merge region as specified in the template document. Case-insensitive.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"); } /** * An example of a "data entity" class in your application. */ public class Customer { public Customer(String aFullName, String anAddress) throws Exception { mFullName = aFullName; mAddress = anAddress; } public String getFullName() throws Exception { return mFullName; } public void setFullName(String value) throws Exception { mFullName = value; } public String getAddress() throws Exception { return mAddress; } public void setAddress(String value) throws Exception { mAddress = value; } private String mFullName; private String mAddress; } /** * An example of a typed collection that contains your "data" objects. */ public class CustomerList extends ArrayList { public Customer get(int index) { return (Customer)super.get(index); } public void set(int index, Customer value) { super.set(index, value); } } /** * 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. */ public class CustomerMailMergeDataSource implements IMailMergeDataSource { public CustomerMailMergeDataSource(CustomerList customers) throws Exception { mCustomers = customers; // When the data source is initialized, it must be positioned before the first record. mRecordIndex= -1; } /** * The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions. */ public String getTableName() throws Exception { return "Customer"; } /** * Aspose.Words calls this method to get a value for every data field. */ public boolean getValue(String fieldName, Object[] fieldValue) throws Exception { if (fieldName.equals("FullName")) { fieldValue[0] = mCustomers.get(mRecordIndex).getFullName(); return true; } else if (fieldName.equals("Address")) { 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; } } /** * A standard implementation for moving to a next record in a collection. */ public boolean moveNext() throws Exception { if (!isEof()) mRecordIndex++; return (!isEof()); } public IMailMergeDataSource getChildDataSource(String tableName) throws Exception { return null; } private boolean isEof() throws Exception { return (mRecordIndex >= mCustomers.size()); } private final CustomerList mCustomers; private int mRecordIndex; }
getValue | |
public abstract boolean getValue(java.lang.String fieldName, java.lang.Object[] fieldValue) throws java.lang.Exception |
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.
fieldName
- The name of the data field.fieldValue
- Returns the field value.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"); } /** * An example of a "data entity" class in your application. */ public class Customer { public Customer(String aFullName, String anAddress) throws Exception { mFullName = aFullName; mAddress = anAddress; } public String getFullName() throws Exception { return mFullName; } public void setFullName(String value) throws Exception { mFullName = value; } public String getAddress() throws Exception { return mAddress; } public void setAddress(String value) throws Exception { mAddress = value; } private String mFullName; private String mAddress; } /** * An example of a typed collection that contains your "data" objects. */ public class CustomerList extends ArrayList { public Customer get(int index) { return (Customer)super.get(index); } public void set(int index, Customer value) { super.set(index, value); } } /** * 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. */ public class CustomerMailMergeDataSource implements IMailMergeDataSource { public CustomerMailMergeDataSource(CustomerList customers) throws Exception { mCustomers = customers; // When the data source is initialized, it must be positioned before the first record. mRecordIndex= -1; } /** * The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions. */ public String getTableName() throws Exception { return "Customer"; } /** * Aspose.Words calls this method to get a value for every data field. */ public boolean getValue(String fieldName, Object[] fieldValue) throws Exception { if (fieldName.equals("FullName")) { fieldValue[0] = mCustomers.get(mRecordIndex).getFullName(); return true; } else if (fieldName.equals("Address")) { 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; } } /** * A standard implementation for moving to a next record in a collection. */ public boolean moveNext() throws Exception { if (!isEof()) mRecordIndex++; return (!isEof()); } public IMailMergeDataSource getChildDataSource(String tableName) throws Exception { return null; } private boolean isEof() throws Exception { return (mRecordIndex >= mCustomers.size()); } private final CustomerList mCustomers; private int mRecordIndex; }
moveNext | |
public abstract boolean moveNext() throws java.lang.Exception |
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"); } /** * An example of a "data entity" class in your application. */ public class Customer { public Customer(String aFullName, String anAddress) throws Exception { mFullName = aFullName; mAddress = anAddress; } public String getFullName() throws Exception { return mFullName; } public void setFullName(String value) throws Exception { mFullName = value; } public String getAddress() throws Exception { return mAddress; } public void setAddress(String value) throws Exception { mAddress = value; } private String mFullName; private String mAddress; } /** * An example of a typed collection that contains your "data" objects. */ public class CustomerList extends ArrayList { public Customer get(int index) { return (Customer)super.get(index); } public void set(int index, Customer value) { super.set(index, value); } } /** * 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. */ public class CustomerMailMergeDataSource implements IMailMergeDataSource { public CustomerMailMergeDataSource(CustomerList customers) throws Exception { mCustomers = customers; // When the data source is initialized, it must be positioned before the first record. mRecordIndex= -1; } /** * The name of the data source. Used by Aspose.Words only when executing mail merge with repeatable regions. */ public String getTableName() throws Exception { return "Customer"; } /** * Aspose.Words calls this method to get a value for every data field. */ public boolean getValue(String fieldName, Object[] fieldValue) throws Exception { if (fieldName.equals("FullName")) { fieldValue[0] = mCustomers.get(mRecordIndex).getFullName(); return true; } else if (fieldName.equals("Address")) { 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; } } /** * A standard implementation for moving to a next record in a collection. */ public boolean moveNext() throws Exception { if (!isEof()) mRecordIndex++; return (!isEof()); } public IMailMergeDataSource getChildDataSource(String tableName) throws Exception { return null; } private boolean isEof() throws Exception { return (mRecordIndex >= mCustomers.size()); } private final CustomerList mCustomers; private int mRecordIndex; }