Difference between revisions of "Documentation/DevGuide/Database/The Descriptor Pattern"

Revision as of 12:09, 1 November 2007

The descriptor is a special kind of object that mirrors the structure of the object which should be appended to a container object. This means that a descriptor, once created, can be appended more than once with only small changes to the structure. For example, when appending columns to the columns container, we:

• Create one descriptor with com.sun.star.sdbcx.XDataDescriptorFactory.
• Set the needed properties.
• Add the descriptor to the container.
• Adjust some properties, such as the name.
• Add the modified descriptor to the container.
• Repeat the steps, as necessary.

therefore, only create one descriptor to append more than one column.

Descriptor Pattern

• Creating a Table

An important use of the SDBCX layer is that it is possible to programmatically create tables, along with their columns, indexes, and keys.

The method of creating a table is the same as creating a table with a graphical table design. To create it programmatically is easy. First, create a table object by asking the tables container for its com.sun.star.sdbcx.XDataDescriptorFactory interface. When the createDataDescriptor method is called, the com.sun.star.beans.XPropertySet interface of an object that implements the service com.sun.star.sdbcx.TableDescriptor is returned. As described above, use this descriptor to create a new table in the database, by adding the descriptor to the Tables container. Before appending the descriptor, append the columns to the table descriptor. Use the same method as with the containers used in the SDBCX layer. On the column object, some properties need to be set, such as Name, and Type. The properties to be set depend on the SDBC data type of the column.

The column name must be unique in the columns container.

After the columns are appended, add the TableDescriptor object to its container or define some key objects, such as a primary key.

 // create the table salesmen
 public static void createTableSalesMen(XNameAccess xTables) throws Exception, SQLException {
     XDataDescriptorFactory xTabFac = (XDataDescriptorFactory)UnoRuntime.queryInterface(
         XDataDescriptorFactory.class, xTables);
 
     if (xTabFac != null) {
         // create the new table
         XPropertySet xTable = xTabFac.createDataDescriptor();
         // set the name of the new table
         xTable.setPropertyValue("Name", "SALESMAN");
         
         // append the columns
         XColumnsSupplier xColumSup = (XColumnsSupplier)UnoRuntime.queryInterface(
             XColumnsSupplier.class,xTable);
         XDataDescriptorFactory xColFac = (XDataDescriptorFactory)UnoRuntime.queryInterface(
             XDataDescriptorFactory.class, xColumSup.getColumns());
         XAppend xAppend = (XAppend)UnoRuntime.queryInterface(XAppend.class, xColFac);
         
         // we only need one descriptor
         XPropertySet xCol = xColFac.createDataDescriptor();
         
         // create first column and append
         xCol.setPropertyValue("Name", "SNR");
         xCol.setPropertyValue("Type", new Integer(DataType.INTEGER));
         xCol.setPropertyValue("IsNullable", new Integer(ColumnValue.NO_NULLS));
         xAppend.appendByDescriptor(xCol);
         // 2nd only set the properties which differ
         xCol.setPropertyValue("Name", "FIRSTNAME");
         xCol.setPropertyValue("Type", new Integer(DataType.VARCHAR));
         xCol.setPropertyValue("IsNullable", new Integer(ColumnValue.NULLABLE));
         xCol.setPropertyValue("Precision", new Integer(50));
         xAppend.appendByDescriptor(xCol);
         // 3rd only set the properties which differ
         xCol.setPropertyValue("Name", "LASTNAME");
         xCol.setPropertyValue("Precision", new Integer(100));
         xAppend.appendByDescriptor(xCol);
         // 4th only set the properties which differ
         xCol.setPropertyValue("Name", "STREET");
         xCol.setPropertyValue("Precision",n ew Integer(50));
         xAppend.appendByDescriptor(xCol);
         // 5th only set the properties which differ
         xCol.setPropertyValue("Name", "STATE");
         xAppend.appendByDescriptor(xCol);
         // 6th only set the properties which differ
         xCol.setPropertyValue("Name", "ZIP");
         xCol.setPropertyValue("Type", new Integer(DataType.INTEGER));
         xCol.setPropertyValue("Precision", new Integer(10)); // default value integer
         xAppend.appendByDescriptor(xCol);
         // 7th only set the properties which differs
         xCol.setPropertyValue("Name", "BIRTHDATE");
         xCol.setPropertyValue("Type", new Integer(DataType.DATE));
         xCol.setPropertyValue("Precision", new Integer(10)); // default value integer
         xAppend.appendByDescriptor(xCol);
         
         // now we create the primary key
         XKeysSupplier xKeySup = (XKeysSupplier)UnoRuntime.queryInterface(XKeysSupplier.class, xTable);
         XDataDescriptorFactory xKeyFac = (XDataDescriptorFactory)UnoRuntime.queryInterface(
             XDataDescriptorFactory.class,xKeySup.getKeys());
         XAppend xKeyAppend = (XAppend)UnoRuntime.queryInterface(XAppend.class, xKeyFac);
         
         XPropertySet xKey = xKeyFac.createDataDescriptor();
         xKey.setPropertyValue("Type", new Integer(KeyType.PRIMARY));
         // now append the columns to key
         XColumnsSupplier xKeyColumSup = (XColumnsSupplier)UnoRuntime.queryInterface(
             XColumnsSupplier.class, xKey);
         XDataDescriptorFactory xKeyColFac = (XDataDescriptorFactory)UnoRuntime.queryInterface(
             XDataDescriptorFactory.class,xKeyColumSup.getColumns());
         XAppend xKeyColAppend = (XAppend)UnoRuntime.queryInterface(XAppend.class, xKeyColFac);
         
         // we only need one descriptor
         XPropertySet xKeyCol = xKeyColFac.createDataDescriptor();
         xKeyCol.setPropertyValue("Name", "SNR");
         // append the key column
         xKeyColAppend.appendByDescriptor(xKeyCol);
         // append the key
         xKeyAppend.appendByDescriptor(xKey);
         // the last step is to append the new table to the tables collection
         XAppend xTableAppend = (XAppend)UnoRuntime.queryInterface(XAppend.class, xTabFac);
         xTableAppend.appendByDescriptor(xTable);
     }
 }