WebSphere Commerce extended XPath notation

WebSphere Commerce uses an extended XPath notation as the query language to identify the parts of the logical model you want to query. XPath is an industry standard language for addressing parts of an XML document, and the WebSphere Commerce extended XPath notation has some extensions to this standard.

The XML documents being addressed by the extended XPath notation are Business Object Documents (BODs), which are converted to a Java class called a Service Data Object (SDO). Each SDO object instance is represented as an element. Its properties can be represented as attributes (in simple case such as String) or as elements (when its properties reference another SDO object). Usually this XML document is governed by a XML schema which defines the allowable content and semantics. These SDO objects and XML schema form the WebSphere Commerce logical model.

When you use the XPath language, the XPath should match the logical schema of the response Noun. For example, given the following noun XML:

<Catalog>
    <CatalogGroup>
      <Name>MyCatalogGroupName</Name>
    </CatalogGroup>
  </Catalog>

The following example shows how to look up by Name:

/CatalogGroup[Name='MyCatalogGroupName']

the XPath expression matches the structure of the logical schema.

 

WebSphere Commerce extended XPath query notation

The syntax of specifying a query expression is shown here using the extended Backus-Naur Form notation:

• <XPath Extended Query Expression> := <Control Parameters> <XPath Query>

• <Control Parameters> : = '{' '_wcf.ap='<AccessProfile> [ (& | ;) <Name>'='<Value> ]* '}'

• <AccessProfile> : = <Literal>

• <Value> := <Literal>

• <XPath Query> := '/' RelativeLocationPath

• <RelativeLocationPath> := Step | RelativeLocationPath '/' Step

• <Step> := Name (<Predicate>)*

• <Predicate> := '[' <PredicateExpr> ']'

• <PredicateExpr> := <OrExpr>

• <OrExpr> := <AndExpr> | <OrExpr> 'or' <AndExpr>

• <AndExpr> := <RelationalExpr> | <AndExpr> 'and' <RelationalExpr> | '(' <OrExpr> ')'

• <RelationalExpr> := <Property> <Operator> <Value> | <StringMatchingFunction>'('<LocationPathOperand> ',' <Value>')' | <RelativeLocationPath> | <SearchFunction>'(' <SearchParam> ([ 'and' <SearchParam>]* |[ 'or' <SearchParam>]*)+')'

• <Operator> := '<' | '>' | '<=' | '>=' | '=' | '!='

• <StringMatchingFunction> := 'starts-with' | 'contains'

• <Value> := <Literal> | <Number>

• <SearchParam> := <ComparsionExpr> | <StringMatchingFunction>

• <ComparsionExpr> := <LocationPathOperand> <Operator> <Value>

• <LocationPathOperand> := [<SimpleRelativeLocationPath>] <Property>

• <SimpleRelativeLocationPath> := <Name> ('/' <Name>)*

• <Literal> := (' " ' (<EscapeQuot> | [^"])* ' " ') | (" ' " (<EscapeApos> | [^'])* " ' ")

• <EscapeQuot> := ' "" '

• <EscapeApos> := " '' "

• <Number> := <Digits> ('.' <Digits>?)? | '.' Digits

• <Property> := ('@')?<Name>

• <Name> := (<Letter> | '_') (<Letter> | <Digit> | '_' | '.' | '-' )*

• <Letter> := [a-zA-Z]

• <Digit> := [0-9]

• <Digits> := [0-9]+

Tip:

• Optional items enclosed in square brackets. For example, ['<PredicateExpr']

• Items repeating 0 or more times are suffixed with an asterisk.

• Items repeating 1 or more times are followed by a '+'

• Alternative choices in a production are separated by the ‘|’ symbol. For example, <Alternative A>|<Alternative B>.

• Where items need to be grouped they are enclosed in simple parenthesis ().

The control parameters part of the extended query expression allows the caller to specify additional information as part of the query. Use the control parameters when the query cannot be expressed by an XPath query. In other words, use these parameters if and only if the logical model cannot capture the conditions that express in the query.

For example, the caller of the Member component needs to retrieve information about the current user. The returned object is fetched based on the current userId stored in the command context. In this case, the 'self=true' name-value pair in the extended query expression can be used to indicate to the business logic additional information about the requested object. This information cannot be captured by the logical model. The query looks like this: {self=true;_wcf.ap=IBM_All}/Person.

 

Examples of query expressions

Search for organization by Distinguished Name (DN):

{_wcf.ap=IBM_All}/Organization[OrganizationIdentifier[(DistinguishedName='DN01')]]

The following example shows how to look up summary information about a catalog entry given its part number:

{_wcf.ap=IBM_Summary}/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='FU0101' or PartNumber='FU0102')]]]

Related Concepts

Get Request and the Show Response

Related tasks

Create a new search expression