com.aspose.words

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 customDataSource() throws Exception {
      // Create a destination document for the mail merge
      Document doc = new Document();
      DocumentBuilder builder = new DocumentBuilder(doc);
      builder.insertField(" MERGEFIELD FullName ");
      builder.insertParagraph();
      builder.insertField(" MERGEFIELD Address ");
  
      // 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"));
  
      // 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(getArtifactsDir() + "MailMergeCustom.CustomDataSource.docx");
  }
  
  /**
   * An example of a "data entity" class in your application.
   */
  public class Customer {
      public Customer(final String aFullName, final String anAddress) {
          mFullName = aFullName;
          mAddress = anAddress;
      }
  
      public String getFullName() {
          return mFullName;
      }
  
      public void setFullName(final String value) {
          mFullName = value;
      }
  
      public String getAddress() {
          return mAddress;
      }
  
      public void setAddress(final String value) {
          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(final int index) {
          return (Customer) super.get(index);
      }
  
      public void set(final int index, final 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(final CustomerList customers) {
          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() {
          return "Customer";
      }
  
      /**
       * Aspose.Words calls this method to get a value for every data field.
       */
      public boolean getValue(final String fieldName, final Ref<Object> fieldValue) throws Exception {
          if (fieldName.equals("FullName")) {
              fieldValue.set(mCustomers.get(mRecordIndex).getFullName());
              return true;
          } else if (fieldName.equals("Address")) {
              fieldValue.set(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.set(null);
              return false;
          }
      }
  
      /**
       * A standard implementation for moving to a next record in a collection.
       */
      public boolean moveNext() {
          if (!isEof()) mRecordIndex++;
  
          return (!isEof());
      }
  
      public IMailMergeDataSource getChildDataSource(final String tableName) {
          return null;
      }
  
      private boolean isEof() {
          return (mRecordIndex >= mCustomers.size());
      }
  
      private final CustomerList mCustomers;
      private int mRecordIndex;
  }

  Returns:

  The name of the data source. Empty string if the data source has no name.

Method Detail

• getChildDataSource

  public abstract IMailMergeDataSource getChildDataSource(java.lang.String tableName)
                                                       throws java.lang.Exception

  The Aspose.Words mail merge engine invokes this method when it encounters a beginning of a nested mail merge region.

  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 getChildDataSource(java.lang.String) on the current data source object. Your implementation needs to return a new data source object that will provide access to the child records of the current parent record. Aspose.Words will use the returned data source to populate the nested mail merge region.

  Below are the rules that the implementation of getChildDataSource(java.lang.String) must follow.

  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 IMailMergeDataSource object that will provide access to the child records of the current record. An example of this is Orders / OrderDetails relationship. Let's assume that the current IMailMergeDataSource object represents the Orders table and it has a current order record. Next, Aspose.Words encounters "MERGEFIELD TableStart:OrderDetails" in the document and invokes getChildDataSource(java.lang.String). You need to create and return a IMailMergeDataSource object that will allow Aspose.Words to access the OrderDetails record for the current order.

  If this data source object does not have a relation to the table with the specified name, then you need to return a IMailMergeDataSource object that will provide access to all records of the specified table.

  If a table with the specified name does not exist, your implementation should return null.

  Parameters:

  tableName - The name of the mail merge region as specified in the template document. Case-insensitive.

  Returns:

  A data source object that will provide access to the data records of the specified table.

  Example:

  Performs mail merge from a custom data source.

  public void customDataSource() throws Exception {
      // Create a destination document for the mail merge
      Document doc = new Document();
      DocumentBuilder builder = new DocumentBuilder(doc);
      builder.insertField(" MERGEFIELD FullName ");
      builder.insertParagraph();
      builder.insertField(" MERGEFIELD Address ");
  
      // 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"));
  
      // 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(getArtifactsDir() + "MailMergeCustom.CustomDataSource.docx");
  }
  
  /**
   * An example of a "data entity" class in your application.
   */
  public class Customer {
      public Customer(final String aFullName, final String anAddress) {
          mFullName = aFullName;
          mAddress = anAddress;
      }
  
      public String getFullName() {
          return mFullName;
      }
  
      public void setFullName(final String value) {
          mFullName = value;
      }
  
      public String getAddress() {
          return mAddress;
      }
  
      public void setAddress(final String value) {
          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(final int index) {
          return (Customer) super.get(index);
      }
  
      public void set(final int index, final 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(final CustomerList customers) {
          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() {
          return "Customer";
      }
  
      /**
       * Aspose.Words calls this method to get a value for every data field.
       */
      public boolean getValue(final String fieldName, final Ref<Object> fieldValue) throws Exception {
          if (fieldName.equals("FullName")) {
              fieldValue.set(mCustomers.get(mRecordIndex).getFullName());
              return true;
          } else if (fieldName.equals("Address")) {
              fieldValue.set(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.set(null);
              return false;
          }
      }
  
      /**
       * A standard implementation for moving to a next record in a collection.
       */
      public boolean moveNext() {
          if (!isEof()) mRecordIndex++;
  
          return (!isEof());
      }
  
      public IMailMergeDataSource getChildDataSource(final String tableName) {
          return null;
      }
  
      private boolean isEof() {
          return (mRecordIndex >= mCustomers.size());
      }
  
      private final CustomerList mCustomers;
      private int mRecordIndex;
  }

• getValue

  public abstract boolean getValue(java.lang.String fieldName, com.aspose.words.ref.Ref 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.

              Ref<String> fieldValue = {null};
              boolean isValueFound = mDataSource.getValue(fieldName, fieldValue);
              String value = isValueFound ? fieldValue.get() : null;
              

  If you implement this method, then when the requested field is found, you should assign the value fieldValue.set(fondValue) 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 customDataSource() throws Exception {
      // Create a destination document for the mail merge
      Document doc = new Document();
      DocumentBuilder builder = new DocumentBuilder(doc);
      builder.insertField(" MERGEFIELD FullName ");
      builder.insertParagraph();
      builder.insertField(" MERGEFIELD Address ");
  
      // 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"));
  
      // 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(getArtifactsDir() + "MailMergeCustom.CustomDataSource.docx");
  }
  
  /**
   * An example of a "data entity" class in your application.
   */
  public class Customer {
      public Customer(final String aFullName, final String anAddress) {
          mFullName = aFullName;
          mAddress = anAddress;
      }
  
      public String getFullName() {
          return mFullName;
      }
  
      public void setFullName(final String value) {
          mFullName = value;
      }
  
      public String getAddress() {
          return mAddress;
      }
  
      public void setAddress(final String value) {
          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(final int index) {
          return (Customer) super.get(index);
      }
  
      public void set(final int index, final 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(final CustomerList customers) {
          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() {
          return "Customer";
      }
  
      /**
       * Aspose.Words calls this method to get a value for every data field.
       */
      public boolean getValue(final String fieldName, final Ref<Object> fieldValue) throws Exception {
          if (fieldName.equals("FullName")) {
              fieldValue.set(mCustomers.get(mRecordIndex).getFullName());
              return true;
          } else if (fieldName.equals("Address")) {
              fieldValue.set(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.set(null);
              return false;
          }
      }
  
      /**
       * A standard implementation for moving to a next record in a collection.
       */
      public boolean moveNext() {
          if (!isEof()) mRecordIndex++;
  
          return (!isEof());
      }
  
      public IMailMergeDataSource getChildDataSource(final String tableName) {
          return null;
      }
  
      private boolean isEof() {
          return (mRecordIndex >= mCustomers.size());
      }
  
      private final CustomerList mCustomers;
      private int mRecordIndex;
  }

• 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 customDataSource() throws Exception {
      // Create a destination document for the mail merge
      Document doc = new Document();
      DocumentBuilder builder = new DocumentBuilder(doc);
      builder.insertField(" MERGEFIELD FullName ");
      builder.insertParagraph();
      builder.insertField(" MERGEFIELD Address ");
  
      // 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"));
  
      // 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(getArtifactsDir() + "MailMergeCustom.CustomDataSource.docx");
  }
  
  /**
   * An example of a "data entity" class in your application.
   */
  public class Customer {
      public Customer(final String aFullName, final String anAddress) {
          mFullName = aFullName;
          mAddress = anAddress;
      }
  
      public String getFullName() {
          return mFullName;
      }
  
      public void setFullName(final String value) {
          mFullName = value;
      }
  
      public String getAddress() {
          return mAddress;
      }
  
      public void setAddress(final String value) {
          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(final int index) {
          return (Customer) super.get(index);
      }
  
      public void set(final int index, final 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(final CustomerList customers) {
          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() {
          return "Customer";
      }
  
      /**
       * Aspose.Words calls this method to get a value for every data field.
       */
      public boolean getValue(final String fieldName, final Ref<Object> fieldValue) throws Exception {
          if (fieldName.equals("FullName")) {
              fieldValue.set(mCustomers.get(mRecordIndex).getFullName());
              return true;
          } else if (fieldName.equals("Address")) {
              fieldValue.set(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.set(null);
              return false;
          }
      }
  
      /**
       * A standard implementation for moving to a next record in a collection.
       */
      public boolean moveNext() {
          if (!isEof()) mRecordIndex++;
  
          return (!isEof());
      }
  
      public IMailMergeDataSource getChildDataSource(final String tableName) {
          return null;
      }
  
      private boolean isEof() {
          return (mRecordIndex >= mCustomers.size());
      }
  
      private final CustomerList mCustomers;
      private int mRecordIndex;
  }