java.lang.Objectcom.aspose.words.Odso
public class Odso
ODSO seems to be the "new" way the newer Microsoft Word versions prefer to use when specifying certain
types of data sources for a mail merge document. ODSO probably first appeared in Microsoft Word 2000. The use of ODSO is poorly documented and the best way to learn how to use the properies of this object
is to create a document with a desired data source manually in Microsoft Word and then open that document using
Aspose.Words and examine the properties of the You do not normally need to create objects of this class directly because ODSO settings
are always available via the Example:
// We'll create a simple document that will act as a destination for mail merge data
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Dear ");
builder.insertField("MERGEFIELD FirstName", "<FirstName>");
builder.write(" ");
builder.insertField("MERGEFIELD LastName", "<LastName>");
builder.writeln(": ");
builder.insertField("MERGEFIELD Message", "<Message>");
// Also we'll need a data source, in this case it will be an ASCII text file
// We can use any character we want as a delimiter, in this case we'll choose '|'
// The delimiter character is selected in the ODSO settings of mail merge settings
String[] lines = {"FirstName|LastName|Message",
"John|Doe|Hello! This message was created with Aspose Words mail merge."};
Files.write(Paths.get(getArtifactsDir() + "Document.Lines.txt"),
(lines + System.lineSeparator()).getBytes(UTF_8),
new StandardOpenOption[]{StandardOpenOption.CREATE, StandardOpenOption.APPEND});
// Set the data source, query and other things
MailMergeSettings mailMergeSettings = doc.getMailMergeSettings();
mailMergeSettings.setMainDocumentType(MailMergeMainDocumentType.MAILING_LABELS);
mailMergeSettings.setDataType(MailMergeDataType.NATIVE);
mailMergeSettings.setDataSource(getArtifactsDir() + "Document.Lines.txt");
mailMergeSettings.setQuery("SELECT * FROM " + doc.getMailMergeSettings().getDataSource());
mailMergeSettings.setLinkToQuery(true);
mailMergeSettings.setViewMergedData(true);
// Office Data Source Object settings
Odso odso = mailMergeSettings.getOdso();
odso.setDataSource(getArtifactsDir() + "Document.Lines.txt");
odso.setDataSourceType(OdsoDataSourceType.TEXT);
odso.setColumnDelimiter('|');
odso.setDataSource(getArtifactsDir() + "Document.Lines.txt");
odso.setFirstRowContainsColumnNames(true);
// ODSO objects can also be cloned
Assert.assertNotSame(odso, odso.deepClone());
// The mail merge will be performed when this document is opened
doc.save(getArtifactsDir() + "Document.MailMergeSettings.docx");
Constructor Summary |
---|
Odso()
|
Property Getters/Setters Summary | ||
---|---|---|
char | getColumnDelimiter() | |
void | setColumnDelimiter(char value) | |
Specifies the character which shall be interpreted as the column delimiter used to separate columns within external data sources. The default value is 0 which means there is no column delimiter defined. | ||
java.lang.String | getDataSource() | |
void | setDataSource(java.lang.String value) | |
Specifies the location of the external data source to be connected to a document to perform the mail merge. The default value is an empty string. | ||
int | getDataSourceType() | |
void | setDataSourceType(int value) | |
Specifies the type of the external data source to be connected to as part of the ODSO connection information for this mail merge.
The default value is |
||
OdsoFieldMapDataCollection | getFieldMapDatas() | |
void | setFieldMapDatas(OdsoFieldMapDataCollection value) | |
Gets or sets a collection of objects that specify how columns from the external data source are mapped to the predefined merge field names in the document. This object is never null. | ||
boolean | getFirstRowContainsColumnNames() | |
void | setFirstRowContainsColumnNames(boolean value) | |
Specifies that a hosting application shall treat the first row of data in the specified external data
source as a header row containing the names of each column in the data source.
The default value is false .
|
||
OdsoRecipientDataCollection | getRecipientDatas() | |
void | setRecipientDatas(OdsoRecipientDataCollection value) | |
Gets or sets a collection of objects that specify inclusion/exclusion of individual records in the mail merge. This object is never null. | ||
java.lang.String | getTableName() | |
void | setTableName(java.lang.String value) | |
Specifies the particular set of data that a source shall be connected to within an external data source. The default value is an empty string. | ||
java.lang.String | getUdlConnectString() | |
void | setUdlConnectString(java.lang.String value) | |
Specifies the Universal Data Link (UDL) connection string used to connect to an external data source. The default value is an empty string. |
Method Summary | ||
---|---|---|
Odso | deepClone() | |
Returns a deep clone of this object. |
Constructor Detail |
---|
public Odso()
Property Getters/Setters Detail |
---|
getColumnDelimiter/setColumnDelimiter | |
public char getColumnDelimiter() / public void setColumnDelimiter(char value) |
RK I have never seen this in use.
Example:
Shows how to execute a mail merge with MailMergeSettings.// We'll create a simple document that will act as a destination for mail merge data Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); builder.write("Dear "); builder.insertField("MERGEFIELD FirstName", "<FirstName>"); builder.write(" "); builder.insertField("MERGEFIELD LastName", "<LastName>"); builder.writeln(": "); builder.insertField("MERGEFIELD Message", "<Message>"); // Also we'll need a data source, in this case it will be an ASCII text file // We can use any character we want as a delimiter, in this case we'll choose '|' // The delimiter character is selected in the ODSO settings of mail merge settings String[] lines = {"FirstName|LastName|Message", "John|Doe|Hello! This message was created with Aspose Words mail merge."}; Files.write(Paths.get(getArtifactsDir() + "Document.Lines.txt"), (lines + System.lineSeparator()).getBytes(UTF_8), new StandardOpenOption[]{StandardOpenOption.CREATE, StandardOpenOption.APPEND}); // Set the data source, query and other things MailMergeSettings mailMergeSettings = doc.getMailMergeSettings(); mailMergeSettings.setMainDocumentType(MailMergeMainDocumentType.MAILING_LABELS); mailMergeSettings.setDataType(MailMergeDataType.NATIVE); mailMergeSettings.setDataSource(getArtifactsDir() + "Document.Lines.txt"); mailMergeSettings.setQuery("SELECT * FROM " + doc.getMailMergeSettings().getDataSource()); mailMergeSettings.setLinkToQuery(true); mailMergeSettings.setViewMergedData(true); // Office Data Source Object settings Odso odso = mailMergeSettings.getOdso(); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setDataSourceType(OdsoDataSourceType.TEXT); odso.setColumnDelimiter('|'); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setFirstRowContainsColumnNames(true); // ODSO objects can also be cloned Assert.assertNotSame(odso, odso.deepClone()); // The mail merge will be performed when this document is opened doc.save(getArtifactsDir() + "Document.MailMergeSettings.docx");
getDataSource/setDataSource | |
public java.lang.String getDataSource() / public void setDataSource(java.lang.String value) |
Example:
Shows how to execute a mail merge with MailMergeSettings.// We'll create a simple document that will act as a destination for mail merge data Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); builder.write("Dear "); builder.insertField("MERGEFIELD FirstName", "<FirstName>"); builder.write(" "); builder.insertField("MERGEFIELD LastName", "<LastName>"); builder.writeln(": "); builder.insertField("MERGEFIELD Message", "<Message>"); // Also we'll need a data source, in this case it will be an ASCII text file // We can use any character we want as a delimiter, in this case we'll choose '|' // The delimiter character is selected in the ODSO settings of mail merge settings String[] lines = {"FirstName|LastName|Message", "John|Doe|Hello! This message was created with Aspose Words mail merge."}; Files.write(Paths.get(getArtifactsDir() + "Document.Lines.txt"), (lines + System.lineSeparator()).getBytes(UTF_8), new StandardOpenOption[]{StandardOpenOption.CREATE, StandardOpenOption.APPEND}); // Set the data source, query and other things MailMergeSettings mailMergeSettings = doc.getMailMergeSettings(); mailMergeSettings.setMainDocumentType(MailMergeMainDocumentType.MAILING_LABELS); mailMergeSettings.setDataType(MailMergeDataType.NATIVE); mailMergeSettings.setDataSource(getArtifactsDir() + "Document.Lines.txt"); mailMergeSettings.setQuery("SELECT * FROM " + doc.getMailMergeSettings().getDataSource()); mailMergeSettings.setLinkToQuery(true); mailMergeSettings.setViewMergedData(true); // Office Data Source Object settings Odso odso = mailMergeSettings.getOdso(); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setDataSourceType(OdsoDataSourceType.TEXT); odso.setColumnDelimiter('|'); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setFirstRowContainsColumnNames(true); // ODSO objects can also be cloned Assert.assertNotSame(odso, odso.deepClone()); // The mail merge will be performed when this document is opened doc.save(getArtifactsDir() + "Document.MailMergeSettings.docx");
getDataSourceType/setDataSourceType | |
public int getDataSourceType() / public void setDataSourceType(int value) |
This setting is purely a suggestion of the data source type that is being used for this mail merge.
Example:
Shows how to execute a mail merge with MailMergeSettings.// We'll create a simple document that will act as a destination for mail merge data Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); builder.write("Dear "); builder.insertField("MERGEFIELD FirstName", "<FirstName>"); builder.write(" "); builder.insertField("MERGEFIELD LastName", "<LastName>"); builder.writeln(": "); builder.insertField("MERGEFIELD Message", "<Message>"); // Also we'll need a data source, in this case it will be an ASCII text file // We can use any character we want as a delimiter, in this case we'll choose '|' // The delimiter character is selected in the ODSO settings of mail merge settings String[] lines = {"FirstName|LastName|Message", "John|Doe|Hello! This message was created with Aspose Words mail merge."}; Files.write(Paths.get(getArtifactsDir() + "Document.Lines.txt"), (lines + System.lineSeparator()).getBytes(UTF_8), new StandardOpenOption[]{StandardOpenOption.CREATE, StandardOpenOption.APPEND}); // Set the data source, query and other things MailMergeSettings mailMergeSettings = doc.getMailMergeSettings(); mailMergeSettings.setMainDocumentType(MailMergeMainDocumentType.MAILING_LABELS); mailMergeSettings.setDataType(MailMergeDataType.NATIVE); mailMergeSettings.setDataSource(getArtifactsDir() + "Document.Lines.txt"); mailMergeSettings.setQuery("SELECT * FROM " + doc.getMailMergeSettings().getDataSource()); mailMergeSettings.setLinkToQuery(true); mailMergeSettings.setViewMergedData(true); // Office Data Source Object settings Odso odso = mailMergeSettings.getOdso(); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setDataSourceType(OdsoDataSourceType.TEXT); odso.setColumnDelimiter('|'); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setFirstRowContainsColumnNames(true); // ODSO objects can also be cloned Assert.assertNotSame(odso, odso.deepClone()); // The mail merge will be performed when this document is opened doc.save(getArtifactsDir() + "Document.MailMergeSettings.docx");
getFieldMapDatas/setFieldMapDatas | |
public OdsoFieldMapDataCollection getFieldMapDatas() / public void setFieldMapDatas(OdsoFieldMapDataCollection value) |
Example:
Shows how to access the collection of data that maps data source columns to merge fields.Document doc = new Document(getMyDir() + "OdsoData.doc"); // This collection defines how columns from an external data source will be mapped to predefined MERGEFIELD, // ADDRESSBLOCK and GREETINGLINE fields during a mail merge OdsoFieldMapDataCollection fieldMapDataCollection = doc.getMailMergeSettings().getOdso().getFieldMapDatas(); Assert.assertEquals(fieldMapDataCollection.getCount(), 30); int index = 0; for (OdsoFieldMapData data : fieldMapDataCollection) { System.out.println(MessageFormat.format("Field map data index #{0}, type \"{1}\":", index++, data.getType())); if (data.getType() != OdsoFieldMappingType.NULL) { System.out.println(MessageFormat.format("\tColumn named {0}, number {1} in the data source mapped to merge field named {2}.", data.getName(), data.getColumn(), data.getMappedName())); } else { System.out.println("\tNo valid column to field mapping data present."); } Assert.assertNotEquals(data, data.deepClone()); }
getFirstRowContainsColumnNames/setFirstRowContainsColumnNames | |
public boolean getFirstRowContainsColumnNames() / public void setFirstRowContainsColumnNames(boolean value) |
false
.
RK I have never seen this in use.
Example:
Shows how to execute a mail merge with MailMergeSettings.// We'll create a simple document that will act as a destination for mail merge data Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); builder.write("Dear "); builder.insertField("MERGEFIELD FirstName", "<FirstName>"); builder.write(" "); builder.insertField("MERGEFIELD LastName", "<LastName>"); builder.writeln(": "); builder.insertField("MERGEFIELD Message", "<Message>"); // Also we'll need a data source, in this case it will be an ASCII text file // We can use any character we want as a delimiter, in this case we'll choose '|' // The delimiter character is selected in the ODSO settings of mail merge settings String[] lines = {"FirstName|LastName|Message", "John|Doe|Hello! This message was created with Aspose Words mail merge."}; Files.write(Paths.get(getArtifactsDir() + "Document.Lines.txt"), (lines + System.lineSeparator()).getBytes(UTF_8), new StandardOpenOption[]{StandardOpenOption.CREATE, StandardOpenOption.APPEND}); // Set the data source, query and other things MailMergeSettings mailMergeSettings = doc.getMailMergeSettings(); mailMergeSettings.setMainDocumentType(MailMergeMainDocumentType.MAILING_LABELS); mailMergeSettings.setDataType(MailMergeDataType.NATIVE); mailMergeSettings.setDataSource(getArtifactsDir() + "Document.Lines.txt"); mailMergeSettings.setQuery("SELECT * FROM " + doc.getMailMergeSettings().getDataSource()); mailMergeSettings.setLinkToQuery(true); mailMergeSettings.setViewMergedData(true); // Office Data Source Object settings Odso odso = mailMergeSettings.getOdso(); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setDataSourceType(OdsoDataSourceType.TEXT); odso.setColumnDelimiter('|'); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setFirstRowContainsColumnNames(true); // ODSO objects can also be cloned Assert.assertNotSame(odso, odso.deepClone()); // The mail merge will be performed when this document is opened doc.save(getArtifactsDir() + "Document.MailMergeSettings.docx");
getRecipientDatas/setRecipientDatas | |
public OdsoRecipientDataCollection getRecipientDatas() / public void setRecipientDatas(OdsoRecipientDataCollection value) |
Example:
Shows how to access the collection of data that designates merge data source records to be excluded from a merge.Document doc = new Document(getMyDir() + "OdsoData.doc"); // Records in this collection that do not have the "Active" flag set to true will be excluded from the mail merge OdsoRecipientDataCollection odsoRecipientDataCollection = doc.getMailMergeSettings().getOdso().getRecipientDatas(); Assert.assertEquals(odsoRecipientDataCollection.getCount(), 70); int index = 0; for (OdsoRecipientData data : odsoRecipientDataCollection) { System.out.println(MessageFormat.format("Odso recipient data index #{0}, will {1}be imported upon mail merge.", index++, (data.getActive() ? "" : "not "))); System.out.println(MessageFormat.format("\tColumn #{0}", data.getColumn())); System.out.println(MessageFormat.format("\tHash code: {0}", data.getHash())); System.out.println(MessageFormat.format("\tContents array length: {0}", data.getUniqueTag().length)); Assert.assertNotEquals(data, data.deepClone()); }
getTableName/setTableName | |
public java.lang.String getTableName() / public void setTableName(java.lang.String value) |
Example:
Shows how to execute a mail merge while connecting to an external data source.Document doc = new Document(getMyDir() + "OdsoData.doc"); Odso odso = doc.getMailMergeSettings().getOdso(); System.out.println(MessageFormat.format("File will connect to data source located in:\n\t\"{0}\"", odso.getDataSource())); System.out.println(MessageFormat.format("Source type:\n\t{0}", odso.getDataSourceType())); System.out.println(MessageFormat.format("Connection string:\n\t{0}", odso.getUdlConnectString())); System.out.println(MessageFormat.format("Table:\n\t{0}", odso.getTableName())); System.out.println(MessageFormat.format("Query:\n\t{0}", doc.getMailMergeSettings().getQuery()));
getUdlConnectString/setUdlConnectString | |
public java.lang.String getUdlConnectString() / public void setUdlConnectString(java.lang.String value) |
Example:
Shows how to execute a mail merge while connecting to an external data source.Document doc = new Document(getMyDir() + "OdsoData.doc"); Odso odso = doc.getMailMergeSettings().getOdso(); System.out.println(MessageFormat.format("File will connect to data source located in:\n\t\"{0}\"", odso.getDataSource())); System.out.println(MessageFormat.format("Source type:\n\t{0}", odso.getDataSourceType())); System.out.println(MessageFormat.format("Connection string:\n\t{0}", odso.getUdlConnectString())); System.out.println(MessageFormat.format("Table:\n\t{0}", odso.getTableName())); System.out.println(MessageFormat.format("Query:\n\t{0}", doc.getMailMergeSettings().getQuery()));
Method Detail |
---|
deepClone | |
public Odso deepClone() |
Example:
Shows how to execute a mail merge with MailMergeSettings.// We'll create a simple document that will act as a destination for mail merge data Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); builder.write("Dear "); builder.insertField("MERGEFIELD FirstName", "<FirstName>"); builder.write(" "); builder.insertField("MERGEFIELD LastName", "<LastName>"); builder.writeln(": "); builder.insertField("MERGEFIELD Message", "<Message>"); // Also we'll need a data source, in this case it will be an ASCII text file // We can use any character we want as a delimiter, in this case we'll choose '|' // The delimiter character is selected in the ODSO settings of mail merge settings String[] lines = {"FirstName|LastName|Message", "John|Doe|Hello! This message was created with Aspose Words mail merge."}; Files.write(Paths.get(getArtifactsDir() + "Document.Lines.txt"), (lines + System.lineSeparator()).getBytes(UTF_8), new StandardOpenOption[]{StandardOpenOption.CREATE, StandardOpenOption.APPEND}); // Set the data source, query and other things MailMergeSettings mailMergeSettings = doc.getMailMergeSettings(); mailMergeSettings.setMainDocumentType(MailMergeMainDocumentType.MAILING_LABELS); mailMergeSettings.setDataType(MailMergeDataType.NATIVE); mailMergeSettings.setDataSource(getArtifactsDir() + "Document.Lines.txt"); mailMergeSettings.setQuery("SELECT * FROM " + doc.getMailMergeSettings().getDataSource()); mailMergeSettings.setLinkToQuery(true); mailMergeSettings.setViewMergedData(true); // Office Data Source Object settings Odso odso = mailMergeSettings.getOdso(); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setDataSourceType(OdsoDataSourceType.TEXT); odso.setColumnDelimiter('|'); odso.setDataSource(getArtifactsDir() + "Document.Lines.txt"); odso.setFirstRowContainsColumnNames(true); // ODSO objects can also be cloned Assert.assertNotSame(odso, odso.deepClone()); // The mail merge will be performed when this document is opened doc.save(getArtifactsDir() + "Document.MailMergeSettings.docx");