WebSphere Commerce extended XPath notation
When making Get requests for WebSphere Commerce nouns, WebSphere Commerce uses extended XPath notation as the query language to identify which nouns to return. XPath is an industry standard language for addressing parts of an XML document, and the WebSphere Commerce extended XPath notation uses extensions to this standard.
The XPath notion is used because nouns. are defined in an XML schema and can be thought of as XML documents. WebSphere Commerce converts these nouns into a Java class called Service Data Objects (SDOs). SDO properties can be represented as attributes in simple cases such as Strings, or as elements when the SDO properties reference another SDO object. These SDO objects and XML schemas form the WebSphere Commerce logical model.
Mapping XPath notation
When using XPath expressions to request nouns, WebSphere Commerce does not use Java XPath APIs. WebSphere Commerce maps the XPath expression in the Get request to an SQL query which is defined in a query template file (.tpl file). The SQL query contains variables which WebSphere Commerce replaces at runtime. To map an XPath expression to an SQL query, WebSphere Commerce normalizes the XPath expression and associates the expression with an XPath key. To normalize the expression WebSphere Commerce removes the actual data values in the XPath. You can use the XPath key generator to normalize a specific XPath expression. The XPath key generator command-line utility takes an XPath expression as input and generates an XPath key. This key is used to locate the SQL query in the query template file.
/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='ABC123')]]]
To
normalize this query, WebSphere Commerce removes the value for the
PartNumber. The following code demonstrates the normalized form of
this query:/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber=)]]]
WebSphere
Commerce creates a PartNumber variable that can be used within the
SQL statement associated with this XPath. The SQL statement is defined
in a query template file. The following SQL statement demonstrates
the use of the PartNumber variable. This variable, ?PartNumber? is
replaced during runtime with actual data values.SELECT
CATENTRY_ID_1
FROM
(
SELECT
CATENTRY.CATENTRY_ID CATENTRY_ID_1
FROM
CATENTRY
WHERE
CATENTRY.PARTNUMBER IN (?PartNumber?) AND
CATENTRY.MARKFORDELETE = 0 AndPSAgreements
) T1
WHERE EXISTS
(
SELECT
1
FROM
STORECENT
WHERE
CATENTRY_ID_1 = STORECENT.CATENTRY_ID AND
STORECENT.STOREENT_ID IN ( $STOREPATH:catalog$ )
)
For more information about the XPath key generator and normalizing XPath expressions, see Generating your XPath key using the wcs_xpathkey utility
For more information about how XPath expressions map to the SQL query template, see query template file.
You can create your own methods for querying nouns by defining your own XML mappings in a query template file. For more information about creating your own queries, see creating a query.
XPath notation structure
<Catalog>
<CatalogGroup>
<Name>MyCatalogGroupName</Name>
</CatalogGroup>
</Catalog>
The following XPath expression example shows how to get CatalogGroup
nouns
based on the name attribute:/CatalogGroup[Name='MyCatalogGroupName']
{control parameters}/root node[predicate expressions]
- The control parameters specify access controls or identify that
the query conditions cannot be captured by the logical model. This
parameter identifies how much data is to return for the objects queried.
For example, a control parameter
{_wcf.ap=IBM_Admin_All}
is an access profile. Access profiles map to queries in the query template file and indicate that an administrative view of the object information is to be returned. Control parameters that cannot be captured by the logical model can include requests to return information about the current user or for a specific language. For example, the control parameter{self=true}
indicates that information from the object is to be retrieved based on the current user. This information cannot be captured by the logical model and is based on the current user ID stored in the command context. - The root node is typically the name of the noun to be returned. It is the root element of the XML schema for the noun. In the previous example, the root node is CatalogGroup which is denoted by /CatalogGroup
- The predicate expressions identify the parameters for the information that the query is to retrieve. Each parameter is used in a conditional statement that must be met for the nouns to be returned. The predicate expression is defined with square brackets [predicate expression]. In the previous example, the query is to return CatalogGroup nouns where the CatalogGroup has the name 'MyCatalogGroupName'.
Creating XPath expressions
When creating your own XPath expressions you can create simple and complex expressions. Typically simple XPath expressions are explicitly defined and mapped to SQL queries in the query template files. Websphere Commerce, however, does provide another, more dynamic, way to query objects. You can use the search() function to create a more complex XPath expression to query objects. The search() function can be used to reduce the number queries that a developer needs to create. The search() function can be placed in a predicate expression that is within an XPath expression. When you use this search expression, you do not have to define each query in the query template file. WebSphere Commerce automatically generates the query at runtime based on the contents within your search expression. For more information about creating XPath expressions with the search() function, see parametric search support.
- Control parameters - all control parameters are defined within
a single set of
{ }
brackets. - Control parameters - ensure that you include required prefixes
when defining parameters. All access profiles are prefixed with
_wcf.ap=
. For example to define the IBM_Admin_All access profile use{_wcf.ap=IBM_Admin_All}
- Control parameters - to add additional parameters use a semicolon.
For example
{self=true; _wcf.ap=IBM_Admin_All; _wcf.dataLanguageIds='-1'}
- Root node - the root node must be identified by a forward slash
'/'
followed by the relative path. - Predicate expressions - all predicate expressions are defined
within sets of
[ ]
brackets. - Predicate expressions - you can nest expressions to define queries
that are to return information based on multiple conditions. For example,
the expression
[OrganizationIdentifier[(DistinguishedName='DN01')]]
defines that the query is to return nouns that have anOrganizationIdentifier
with aDistinguishedName
of'DN01'
- Predicate expressions - you use the 'search' function with XPath
expressions. Identify the search function,
search()
, within the predicate and include the search parameters within the set of( )
parenthesis. For example, the root node and predicate expression/CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T')]
identifies a search expression. This expression identifies thatCatalogGroup
information is to be returned when theGroupIdentifier
is'T'
. - Control parameters and predicate expressions - you can use standard
operators such as
'<' '<=' '>' '>=' '=' '!=' '&' '|'
- Control parameters and predicate expressions - Items repeating 0 or more times are suffixed with an asterisk.
- Control parameters and predicate expressions - Items repeating 1 or more times are followed by a '+'
- Control parameters and predicate expressions - Where items need to be grouped enclose the items in simple parenthesis ().
Examples of XPath expressions
To help you create XPath expressions to query your logical models, the following sample expressions demonstrate valid simple XPath expression syntax:
{_wcf.ap=IBM_Admin_All}/Organization[OrganizationIdentifier[(DistinguishedName='DN01')]]
In the preceding example, the XPath expression defines
a query to return organization information based on the distinguished
name of the organization. This expression is composed of: - The control parameter
{_wcf.ap=IBM_Admin_All}
which is an access profile that identifies that an administrative view of all information for the objects is to be returned. - The root node
/Organization
which identifies the XPath expression is querying for information within theOrganization
node in the XML document. - The predicate expression
[OrganizationIdentifier[(DistinguishedName='DN01')]]
. This predicate identifies that the query is to return only the information for organizations with anOrganizationIdentifier
that has aDistinguishedName
of'DN01'
.
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='DU0101' or PartNumber='DU0102')]]]
In the preceding example, The expression defines a query
to retrieve summary information about a catalog entry given its part
number. This XPath expression is composed of:- The control parameters
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}
. These parameters identify that the query is to return an administrative view of the summary information for the objects in the specified store language. - The root node
/CatalogEntry
identifies the XPath expression returnsCatalogEntry
nouns. - The predicate expression
[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='DU0101' or PartNumber='DU0102')]]]
. This predicate identifies that the query is to return catalog entries where theCatalogEntryIdentifier
contains anExternalIdentifier
that is aPartNumber
with a value of eitherDU0101
orDU0102
.
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}/CatalogEntry[ParentCatalogGroupIdentifier[(UniqueID='10128')]]
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogGroup[ParentCatalogGroupIdentifier[(UniqueID='10125')]
{_wcf.ap=IBM_Admin_CatalogEntryMerchandisingAssociations;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[(UniqueID='10541')]]
{_wcf.ap=IBM_Admin_CatalogEntryAttachmentReference;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[(UniqueID='10541')]]
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogGroup[@topCatalogGroup='true']
Examples of query expressions with search functions
To help you create XPath expressions that use search functions to query your logical models, the following sample expressions demonstrate valid XPath expression syntax:
{_wcf.ap=IBM_Admin_CatalogGroupAllParentsDetails;_wcf.dataLanguageIds='-1'}/CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T' or Description/Name='T')]
In this example, the XPath expression defines a query
that returns CatalogGroup
information based on search
results. The expression identifies that WebSphere Commerce is to return
information for catalog groups with either a GroupIdentifier
or
a Description/Name
with a value 'T'
.
The search function specifies to search for the GroupIdentifier
within
the ExternalIdentifier
node for the CatalogGroupIdentifier
of
a CatalogGroup
.{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' or Description/Name='T')]
In this example, the expression includes a search function
with both a simple search expression and a wildcard search expression.
The wildcard search, specifies to query for any catalogEntryTypeCode
contained
in the CatalogEntry
node that has a value of 'PackageBean'
or 'DynamicKitBean'
.
This wildcard search specifies to query all nodes within the CatalogEntry
root
node, regardless of the relative path of the catalogEntryTypeCode
location.
The simple search expression operates as shown in the previous search
function example. This search expression combines with the wildcard
search expression to specify that only information that matches both
search expressions is to be returned.{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(starts-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or starts-with(Description/Name, 'T'))]
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='ProductBean' or @catalogEntryTypeCode='BundleBean' or @catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(starts-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') and Description/Name='C' and starts-with(CatalogEntryAttribute/Attributes/mfPartNumber, 'T') and CatalogEntryAttribute/Attributes/mfName='B') and ParentCatalogGroupIdentifier[ExternalIdentifier[GroupIdentifier='Bottom']]]
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='BundleBean') and search(contains(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or contains(Description/Name, 'T'))]
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='BundleBean') and search(ends-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or ends-with(Description/Name, 'T'))]
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' or CatalogEntryIdentifier/ExternalIdentifier/PartNumber='B' or Description/Name='T' or Description/Name='B')]