Configuring Sun Master Indexes

Creating Master Index Blocking Queries

Note –

MySQL is only supported with Java CAPS Release 6 Update 1.

By default, one blocking query is predefined in query.xml. If the default query does not meet your requirements, you can define new queries for the master index application. You can either use an existing query builder class or create a custom query builder by creating a custom plug-in (for more information, see Implementing Master Index Custom Plug-ins in Developing Sun Master Indexes ). Blocking queries contain block definitions, which define the groups of fields used for each query pass and how those groups are processed. Each block definition contains one or more set of query blocks. Each query block defines the query rules for one of the groups of fields that make up the block definition. You can further configure a blocking query by filtering out unwanted values from the query process. For more information, see Filtering Default Values From Master Index Processes.

The changes you make on the Query page of the Configuration Editor are reflected in query.xml. For more information about this file and the configurable query options, see Query Configuration in Understanding Sun Master Index Configuration Options . If you create a new query to use from the MIDM, make sure to add that query to one of the search definitions in midm.xml.

You can create blocking queries either through the Configuration Editor or by modifying the XML file directly. Both methods are described here.

To Create a Blocking Query (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.

Click the Query tab.

The Query page appears.

In the Blocking Queries section, click Add.

The Blocking Query Builder dialog box appears.

In the Query Builder section, enter the fields described in Master Index Query Builder Dialog Box Fields and XML Elements.

Do the following for each query block you want to include in the query:
1. In the Block Definitions section, click Add.
  
  The Block Definition dialog box appears.
2. In the Block Name field, enter a unique name for the query block.
3. (Optional) In the Hint field, define MySQL, Oracle or SQL Server hints for the query block.
  
  For SQL Server, you can only use OPTION hints.
4. In the Block By section, click Add.
  
  The Block Rule dialog box appears, where you can specify a field to include in the query block.
5. Enter values for the fields on the dialog box as described in Master Index Query Block Fields and XML Elements, and then click OK.
6. For each field to include in the query block, repeat the previous two steps.
7. When you are done specifying fields for the rule, click OK on the Block Definition dialog box.

For each query block you want to create for this query, repeat the previous step.

When you are done defining the query blocks, click OK.

On the Configuration Editor toolbar, click Save.

To define values to exclude as criteria during the query process, see Filtering Default Values From Master Index Processes.

To Create a Blocking Query (XML Editor)

In the Projects window, expand the Configuration node in the project you want to modify, and then double-click query.xml.

The file opens in the NetBeans XML editor.

Create a new query-builder element in the QueryBuilderConfig element.

Make sure the new element is created outside of any existing query-builder elements.

For the new query-builder element, define the attributes listed in Master Index Query Builder Dialog Box Fields and XML Elements.

For example:

<query-builder name="PHONETIC-SEARCH" class=
  "com.sun.mdm.index.user.CustomQueryBuilder" 
  parser-class= 
  "com.sun.mdm.index.configurator.impl.querybuilder.KeyValueConfiguration"
   standardize="false" phoneticize="true">
</query-builder>

Create a new config element between the query-builder tags.

To create a query block, do the following:

In the new config element, create a new block-definition element with a number attribute and assign a unique ID code to the number attribute.

For example:

<query-builder name="BLOCKING-SEARCH" class=
  "com.sun.mdm.index.querybuilder.BlockingQueryBuilder" 
  parser-class=
  "com.sun.mdm.index.configurator.impl.querybuilder.
KeyValueConfiguration"
standardize="true" phoneticize="true">
   <config>
      <block-definition number="ID1">
      </block-definition>
   </config>
</query-builder>

To add a database hint, create and define a new hint element in the new block-definition element.

The following example illustrates an Oracle hint.
<config> <block-definition number="ID1"> <hint>FIRST_ROWS_100</hint> </block-definition> <config>
Tip –
Hints are especially useful when a blocking query uses only child object fields; the hint can specify to scan the child object table first. For SQL Server, only OPTION hints are supported.

In the new block-definition element, create a block-rule element.

For each field in the data block, create the elements and attributes listed in Master Index Query Block Fields and XML Elements.

The following example illustrates the use of both range and equals elements, as well as upper and lower bounds.

<config>
   <block-definition number="ID1">
      <hint>FIRST_ROWS_100</hint>
      <block-rule>
         <equals>
            <field>Enterprise.SystemSBR.Person.FirstNamePh</field>
            <source>Person.FirstNamePh</source>
         </equals>
         <equals>
            <field>Enterprise.SystemSBR.Person.LastNamePh</field>
            <source>Person.LastNamePh</source>
         </equals>
         <range>
            <field>Enterprise.SystemSBR.Person.DateOfBirth</field>
            <source>Person.DateOfBirth</source>
            <default>
               <lower-bound type=”offset”>-5</lower-bound>
               <upper-bound type=”constant”>2009-01-01
               </upper-bound>
            </default>
         </range>
      </block-rule>
   </block-definition>
<config>

Repeat the previous step for each data block you need to define for the query.

All data blocks for one query must be defined within one config element.

Save and close the file.

To define values to exclude as criteria during the query process, see Filtering Default Values From Master Index Processes.

Master Index Query Block Fields and XML Elements

The following table lists and describes the fields on the Block Rule dialog box of the Configuration Editor, along with the corresponding elements and attributes in query.xml. To see how the XML elements are organized, see the sample in Adding a Query Block to a Master Index Query. For more information about the structure of a query block, see Query Configuration in Understanding Sun Master Index Configuration Options .

Configuration Editor Field

XML Element/Attribute

Description

Field

field

The name of the field to be included in the query block. On the Configuration Editor, you can click Browse to select a field or enter the fully qualified field name manually.

Source

source

The name of the source field in the object from which the criteria is obtained. Click Browse to select a field, or enter the qualified field name manually. An asterisk (*) can be used as a wildcard character.

Tip –

When a field in a child object is defined for a blocking query, use the asterisk wildcard character in the ePath to the source field to ensure all instances of the child object in an incoming message are used as search criteria. Each instance is joined by an OR operator. For example, this configuration:

   <field>Enterprise.SystemSBR.Person.Name.FirstName
   </field>
   <source>Person.Name[*].FirstName</source>

would result in a WHERE clause similar to this:

WHERE Name.FirstName=”Meg” OR Name.FirstName=”Maggie”

Operator

type of search

An indicator of the type of search to perform on the field. On the Configuration Editor, you can select one of the following values from the drop-down list. In the XML file, you specify one of the following names for the XML element that defines one field in a query block.

equals - Performs an exact search against either the criteria or the value defined for the “Use Constants” option.
not-equals - Searches for values that do not equal either the criteria or the value defined for the “Use Constants” option.
greater-than-or-equal - Performs a search for values that are greater than or equal to either the criteria or the value defined for the “Use Constants” option.
less-than-or-equal - Performs a search for values that are less than or equal to either the criteria or the value defined for the “Use Constants” option.
range - Performs a search against a range of either static or user-defined ranges. If you select this option, you must specify upper and lower bounds.

Tip –

If a field is to be used for simple range searching (where the user or incoming message supplies lower and upper limits of the range are supplied) be sure to define that field for range searching in midm.xml for the searches that use this query. For more complex range searches that use offset values or constants instead of user-supplied limits, do not define the field for range searching in midm.xml.

Use Constant/Value

constant

On the Configuration Editor, this is an indicator of whether to use a constant value as the search criteria for the field. When this option is selected, you need to enter the constant in the corresponding Value field. In the XML file, enter the value of the constant in the constant element.

Upper Bound Type

upper-bound/type

For range searching only, the type of value to use for the upper limit of the search range. Select or enter one of the following options.

not defined - No specific upper limit is defined; a user enters the value when performing the search. Be sure to define this field for range searching in the MIDM as well. In the XML file, this is indicated by omitting the upper-bound element.
constant - A specific value is defined to use as the upper limit of the range when no search criteria is entered or when incomplete information is available.
offset - A value to be added to the user-supplied value to determine the upper limit on the search range.

For constant and offset, enter the value in the corresponding Value field.

Lower Bound Type

lower-bound/type

For range searching only, the type of value to use for the lower limit of the search range. Select one of the options listed for Upper Bound Type. If you select offset, the value you specify for the offset will be subtracted from the user-supplied value.

Value (for the upper and lower bounds)

upper-bound

lower-bound

For constant and offset range searching, the upper or lower limit of the range. For constants, this is the upper or lower limit; for offsets, this is the value added to or subtracted from the user-supplied value. It can be numeric, date, or string. In the XML file, the upper-bound and lower-bound elements fall within an element named default.