Coverage Report

Coverage Report - org.jaxen.BaseXPath

Classes in this Package Line Coverage Branch Coverage Complexity

BaseXPath
80%
85%
1.9259259259259258;1.926

1
/*

2
* $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/BaseXPath.java,v 1.40 2005/05/06 17:17:13 elharo Exp $

3
* $Revision: 1.40 $

4
* $Date: 2005/05/06 17:17:13 $

5
*

6
* ====================================================================

7
*

8
* Copyright (C) 2000-2002 bob mcwhirter & James Strachan.

9
* All rights reserved.

10
*

11
* Redistribution and use in source and binary forms, with or without

12
* modification, are permitted provided that the following conditions

13
* are met:

14
*

15
* 1. Redistributions of source code must retain the above copyright

16
* notice, this list of conditions, and the following disclaimer.

17
*

18
* 2. Redistributions in binary form must reproduce the above copyright

19
* notice, this list of conditions, and the disclaimer that follows

20
* these conditions in the documentation and/or other materials

21
* provided with the distribution.

22
*

23
* 3. The name "Jaxen" must not be used to endorse or promote products

24
* derived from this software without prior written permission. For

25
* written permission, please contact license@jaxen.org.

26
*

27
* 4. Products derived from this software may not be called "Jaxen", nor

28
* may "Jaxen" appear in their name, without prior written permission

29
* from the Jaxen Project Management (pm@jaxen.org).

30
*

31
* In addition, we request (but do not require) that you include in the

32
* end-user documentation provided with the redistribution and/or in the

33
* software itself an acknowledgement equivalent to the following:

34
* "This product includes software developed by the

35
* Jaxen Project (http://www.jaxen.org/)."

36
* Alternatively, the acknowledgment may be graphical using the logos

37
* available at http://www.jaxen.org/

38
*

39
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

40
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

41
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

42
* DISCLAIMED. IN NO EVENT SHALL THE Jaxen AUTHORS OR THE PROJECT

43
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

44
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

45
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

46
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

47
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

48
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

49
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

50
* SUCH DAMAGE.

51
*

52
* ====================================================================

53
* This software consists of voluntary contributions made by many

54
* individuals on behalf of the Jaxen Project and was originally

55
* created by bob mcwhirter <bob@werken.com> and

56
* James Strachan <jstrachan@apache.org>. For more information on the

57
* Jaxen Project, please see <http://www.jaxen.org/>.

58
*

59
* $Id: BaseXPath.java,v 1.40 2005/05/06 17:17:13 elharo Exp $

60
*/

61

62

63
package org.jaxen;

64

65
import java.io.Serializable;

66
import java.util.List;

67

68
import org.jaxen.expr.Expr;

69
import org.jaxen.expr.XPathExpr;

70
import org.jaxen.function.BooleanFunction;

71
import org.jaxen.function.NumberFunction;

72
import org.jaxen.function.StringFunction;

73
import org.jaxen.saxpath.XPathReader;

74
import org.jaxen.saxpath.helpers.XPathReaderFactory;

75
import org.jaxen.util.SingletonList;

76

77
/** Base functionality for all concrete, implementation-specific XPaths.

78
*

79
* 

80
* This class provides generic functionality for further-defined

81
* implementation-specific XPaths.

82
* 

83
*

84
* 

85
* If you want to adapt the Jaxen engine so that it can traverse your own

86
* object model, then this is a good base class to derive from.

87
* Typically you only really need to provide your own

88
* {@link org.jaxen.Navigator} implementation.

89
* 

90
*

91
* @see org.jaxen.dom4j.Dom4jXPath XPath for dom4j

92
* @see org.jaxen.jdom.JDOMXPath XPath for JDOM

93
* @see org.jaxen.dom.DOMXPath XPath for W3C DOM

94
*

95
* @author <a href="mailto:bob@werken.com">bob mcwhirter</a>

96
* @author <a href="mailto:jstrachan@apache.org">James Strachan</a>

97
*/

98
public class BaseXPath implements XPath, Serializable

99
{

100
/** Original expression text. */

101
private String exprText;

102

103
/** the parsed form of the XPath expression */

104
private XPathExpr xpath;

105

106
/** the support information and function, namespace and variable contexts */

107
private ContextSupport support;

108

109
/** the implementation-specific Navigator for retrieving XML nodes **/

110
private Navigator navigator;

111

112
/** Construct given an XPath expression string.

113
*

114
* @param xpathExpr the XPath expression

115
*

116
* @throws JaxenException if there is a syntax error while

117
* parsing the expression

118
*/

119
protected BaseXPath(String xpathExpr) throws JaxenException

120 1662
{

121
try

122
{

123 1662
XPathReader reader = XPathReaderFactory.createReader();

124 1662
JaxenHandler handler = new JaxenHandler();

125 1662
reader.setXPathHandler( handler );

126 1662
reader.parse( xpathExpr );

127 1629
this.xpath = handler.getXPathExpr();

128
}

129 33
catch (org.jaxen.saxpath.XPathSyntaxException e)

130
{

131 33
throw new org.jaxen.XPathSyntaxException( e );

132
}

133 0
catch (org.jaxen.saxpath.SAXPathException e)

134
{

135 0
throw new JaxenException( e );

136 1629
}

137

138 1629
this.exprText = xpathExpr;

139 1629
}

140

141
/** Construct given an XPath expression string.

142
*

143
* @param xpathExpr the XPath expression

144
*

145
* @param navigator the XML navigator to use

146
*

147
* @throws JaxenException if there is a syntax error while

148
* parsing the expression

149
*/

150
public BaseXPath(String xpathExpr, Navigator navigator) throws JaxenException

151
{

152 240
this( xpathExpr );

153 239
this.navigator = navigator;

154 239
}

155

156
/** Evaluate this XPath against a given context.

157
*

158
* 

159
* The context of evaluation may be a document,

160
* an element, or a set of elements.

161
* ???? accurate? shouldn't it be any type of node?

162
* 

163
*

164
* 

165
* The return value is either a <code>String</code>,

166
* <code>Double</code>, <code>Boolean</code>, or <code>List</code>

167
* of nodes.

168
* 

169
*

170
* 

171
* When using this method, one must be careful to

172
* test the class of the returned object. If the returned

173
* object is a list, then the items in this

174
* list will be the actual <code>Document</code>,

175
* <code>Element</code>, <code>Attribute</code>, etc. objects

176
* as defined by the concrete XML object-model implementation,

177
* directly from the context document. This method does

178
* not return copies of anything, but merely

179
* returns references to objects within the source document.

180
* 

181
*

182
* @param node the node, node-set or Context object for evaluation.

183
* This value can be null.

184
*

185
* @return the result of evaluating the XPath expression

186
* against the supplied context

187
* @throws JaxenException if an XPath error occurs during expression evaluation

188
*/

189
public Object evaluate(Object node) throws JaxenException

190
{

191 700
List answer = selectNodes(node);

192

193 696
if ( answer != null

194
&&

195
answer.size() == 1 )

196
{

197 693
Object first = answer.get(0);

198

199 693
if ( first instanceof String

200
||

201
first instanceof Number

202
||

203
first instanceof Boolean )

204
{

205 560
return first;

206
}

207
}

208 136
return answer;

209
}

210

211
/** Select all nodes that are selected by this XPath

212
* expression. If multiple nodes match, multiple nodes

213
* will be returned. Nodes will be returned

214
* in document-order, as defined by the XPath

215
* specification.

216
* 

217
*

218
* ???? what if the expression return a non-node-set?

219
*

220
* @param node the node, node-set or Context object for evaluation. This value can be null.

221
*

222
* @return the node-set of all items selected

223
* by this XPath expression

224
* @throws JaxenException if an XPath error occurs during expression evaluation

225
*

226
* @see #selectNodesForContext

227
*/

228
public List selectNodes(Object node) throws JaxenException

229
{

230 1615
Context context = getContext( node );

231 1615
return selectNodesForContext( context );

232
}

233

234
/** Select only the first node selected by this XPath

235
* expression. If multiple nodes match, only one node will be

236
* returned. The selected node will be the first

237
* selected node in document-order, as defined by the XPath

238
* specification.

239
* 

240
*

241
* @param node the node, node-set or Context object for evaluation.

242
* This value can be null.

243
*

244
* @return the node-set of all items selected

245
* by this XPath expression

246
* @throws JaxenException if an XPath error occurs during expression evaluation

247
*

248
* @see #selectNodes

249
*/

250
public Object selectSingleNode(Object node) throws JaxenException

251
{

252 2
List results = selectNodes( node );

253

254 2
if ( results.isEmpty() )

255
{

256 1
return null;

257
}

258

259 1
return results.get( 0 );

260
}

261

262
/**

263
* Returns the XPath string-value of the argument node.

264
*

265
* @param node the node whose value to take

266
* @return the XPath string value of this node

267
* @throws JaxenException if an XPath error occurs during expression evaluation

268
* @deprecated

269
* @see #stringValueOf

270
*/

271
public String valueOf(Object node) throws JaxenException

272
{

273 0
return stringValueOf( node );

274
}

275

276
/** Retrieves the string-value of the result of

277
* evaluating this XPath expression when evaluated

278
* against the specified context.

279
*

280
* 

281
* The string-value of the expression is determined per

282
* the <code>string(..)</code> core function defined

283
* in the XPath specification. This means that an expression

284
* that selects zero nodes will return the empty string,

285
* while an expression that selects one-or-more nodes will

286
* return the string-value of the first node.

287
* 

288
*

289
* @param node the node, node-set or Context object for evaluation. This value can be null.

290
*

291
* @return the string-value of the result of evaluating this expression with the specified context node

292
* @throws JaxenException if an XPath error occurs during expression evaluation

293
*/

294
public String stringValueOf(Object node) throws JaxenException

295
{

296 3
Context context = getContext( node );

297

298 3
Object result = selectSingleNodeForContext( context );

299

300 3
if ( result == null )

301
{

302 1
return "";

303
}

304

305 2
return StringFunction.evaluate( result,

306
context.getNavigator() );

307
}

308

309
/** Retrieve a boolean-value interpretation of this XPath

310
* expression when evaluated against a given context.

311
*

312
* 

313
* The boolean-value of the expression is determined per

314
* the <code>boolean(..)</code> function defined

315
* in the XPath specification. This means that an expression

316
* that selects zero nodes will return <code>false</code>,

317
* while an expression that selects one or more nodes will

318
* return <code>true</code>.

319
* 

320
*

321
* @param node the node, node-set or Context object for evaluation. This value can be null.

322
*

323
* @return the boolean-value of the result of evaluating this expression with the specified context node

324
* @throws JaxenException if an XPath error occurs during expression evaluation

325
*/

326
public boolean booleanValueOf(Object node) throws JaxenException

327
{

328 4
Context context = getContext( node );

329 4
List result = selectNodesForContext( context );

330 4
if ( result == null ) return false;

331 4
return BooleanFunction.evaluate( result, context.getNavigator() ).booleanValue();

332
}

333

334
/** Retrieve a number-value interpretation of this XPath

335
* expression when evaluated against a given context.

336
*

337
* 

338
* The number-value of the expression is determined per

339
* the <code>number(..)</code> core function as defined

340
* in the XPath specification. This means that if this

341
* expression selects multiple nodes, the number-value

342
* of the first node is returned.

343
* 

344
*

345
* @param node the node, node-set or Context object for evaluation. This value can be null.

346
*

347
* @return a <code>Double</code> indicating the numeric value of

348
* evaluating this expression against the specified context

349
* @throws JaxenException if an XPath error occurs during expression evaluation

350
*/

351
public Number numberValueOf(Object node) throws JaxenException

352
{

353 3
Context context = getContext( node );

354 3
Object result = selectSingleNodeForContext( context );

355 3
return NumberFunction.evaluate( result,

356
context.getNavigator() );

357
}

358

359
// Helpers

360

361
/** Add a namespace prefix-to-URI mapping for this XPath

362
* expression.

363
*

364
* 

365
* Namespace prefix-to-URI mappings in an XPath are independent

366
* of those used within any document. Only the mapping explicitly

367
* added to this XPath will be available for resolving the

368
* XPath expression.

369
* 

370
*

371
* 

372
* This is a convenience method for adding mappings to the

373
* default {@link NamespaceContext} in place for this XPath.

374
* If you have installed a specific custom <code>NamespaceContext</code>,

375
* then this method will throw a <code>JaxenException</code>.

376
* 

377
*

378
* @param prefix the namespace prefix

379
* @param uri the namespace URI

380
*

381
* @throws JaxenException if a <code>NamespaceContext</code>

382
* used by this XPath has been explicitly installed

383
*/

384
public void addNamespace(String prefix,

385
String uri) throws JaxenException

386
{

387 2
NamespaceContext nsContext = getNamespaceContext();

388 2
if ( nsContext instanceof SimpleNamespaceContext )

389
{

390 2
((SimpleNamespaceContext)nsContext).addNamespace( prefix,

391
uri );

392 2
return;

393
}

394

395 0
throw new JaxenException("Operation not permitted while using a custom namespace context.");

396
}

397

398

399
// ------------------------------------------------------------

400
// ------------------------------------------------------------

401
// Properties

402
// ------------------------------------------------------------

403
// ------------------------------------------------------------

404

405

406
/** Set a <code>NamespaceContext</code> for use with this

407
* XPath expression.

408
*

409
* 

410
* A <code>NamespaceContext</code> is responsible for translating

411
* namespace prefixes within the expression into namespace URIs.

412
* 

413
*

414
* @param namespaceContext the <code>NamespaceContext</code> to

415
* install for this expression

416
*

417
* @see NamespaceContext

418
* @see NamespaceContext#translateNamespacePrefixToUri

419
*/

420
public void setNamespaceContext(NamespaceContext namespaceContext)

421
{

422 29
getContextSupport().setNamespaceContext(namespaceContext);

423 29
}

424

425
/** Set a <code>FunctionContext</code> for use with this XPath

426
* expression.

427
*

428
* 

429
* A <code>FunctionContext</code> is responsible for resolving

430
* all function calls used within the expression.

431
* 

432
*

433
* @param functionContext the <code>FunctionContext</code> to

434
* install for this expression

435
*

436
* @see FunctionContext

437
* @see FunctionContext#getFunction

438
*/

439
public void setFunctionContext(FunctionContext functionContext)

440
{

441 28
getContextSupport().setFunctionContext(functionContext);

442 28
}

443

444
/** Set a <code>VariableContext</code> for use with this XPath

445
* expression.

446
*

447
* 

448
* A <code>VariableContext</code> is responsible for resolving

449
* all variables referenced within the expression.

450
* 

451
*

452
* @param variableContext The <code>VariableContext</code> to

453
* install for this expression

454
*

455
* @see VariableContext

456
* @see VariableContext#getVariableValue

457
*/

458
public void setVariableContext(VariableContext variableContext)

459
{

460 28
getContextSupport().setVariableContext(variableContext);

461 28
}

462

463
/** Retrieve the <code>NamespaceContext</code> used by this XPath

464
* expression.

465
*

466
* 

467
* A <code>NamespaceContext</code> is responsible for mapping

468
* prefixes used within the expression to namespace URIs.

469
* 

470
*

471
* 

472
* If this XPath expression has not previously had a <code>NamespaceContext</code>

473
* installed, a new default <code>NamespaceContext</code> will be created,

474
* installed and returned.

475
* 

476
*

477
* @return the <code>NamespaceContext</code> used by this expression

478
*

479
* @see NamespaceContext

480
*/

481
public NamespaceContext getNamespaceContext()

482
{

483 3
NamespaceContext answer = getContextSupport().getNamespaceContext();

484 3
if ( answer == null ) {

485 0
answer = createNamespaceContext();

486 0
getContextSupport().setNamespaceContext( answer );

487
}

488 3
return answer;

489
}

490

491
/** Retrieve the <code>FunctionContext</code> used by this XPath

492
* expression.

493
*

494
* 

495
* A <code>FunctionContext</code> is responsible for resolving

496
* all function calls used within the expression.

497
* 

498
*

499
* 

500
* If this XPath expression has not previously had a <code>FunctionContext</code>

501
* installed, a new default <code>FunctionContext</code> will be created,

502
* installed and returned.

503
* 

504
*

505
* @return the <code>FunctionContext</code> used by this expression

506
*

507
* @see FunctionContext

508
*/

509
public FunctionContext getFunctionContext()

510
{

511 0
FunctionContext answer = getContextSupport().getFunctionContext();

512 0
if ( answer == null ) {

513 0
answer = createFunctionContext();

514 0
getContextSupport().setFunctionContext( answer );

515
}

516 0
return answer;

517
}

518

519
/** Retrieve the <code>VariableContext</code> used by this XPath

520
* expression.

521
*

522
* 

523
* A <code>VariableContext</code> is responsible for resolving

524
* all variables referenced within the expression.

525
* 

526
*

527
* 

528
* If this XPath expression has not previously had a <code>VariableContext</code>

529
* installed, a new default <code>VariableContext</code> will be created,

530
* installed and returned.

531
* 

532
*

533
* @return the <code>VariableContext</code> used by this expression

534
*

535
* @see VariableContext

536
*/

537
public VariableContext getVariableContext()

538
{

539 0
VariableContext answer = getContextSupport().getVariableContext();

540 0
if ( answer == null ) {

541 0
answer = createVariableContext();

542 0
getContextSupport().setVariableContext( answer );

543
}

544 0
return answer;

545
}

546

547

548
/** Retrieve the root expression of the internal

549
* compiled form of this XPath expression.

550
*

551
* 

552
* Internally, Jaxen maintains a form of Abstract Syntax

553
* Tree (AST) to represent the structure of the XPath expression.

554
* This is normally not required during normal consumer-grade

555
* usage of Jaxen. This method is provided for hard-core users

556
* who wish to manipulate or inspect a tree-based version of

557
* the expression.

558
* 

559
*

560
* @return the root of the AST of this expression

561
*/

562
public Expr getRootExpr()

563
{

564 0
return xpath.getRootExpr();

565
}

566

567
/** Return the original expression text.

568
*

569
* @return the normalized XPath expression string

570
*/

571
public String toString()

572
{

573 4
return this.exprText;

574
}

575

576
/** Returns the string version of this xpath.

577
*

578
* @return the normalized XPath expression string

579
*

580
* @see #toString

581
*/

582
public String debug()

583
{

584 0
return this.xpath.toString();

585
}

586

587
// ------------------------------------------------------------

588
// ------------------------------------------------------------

589
// Implementation methods

590
// ------------------------------------------------------------

591
// ------------------------------------------------------------

592

593

594
/** Create a {@link Context} wrapper for the provided

595
* implementation-specific object.

596
*

597
* @param node the implementation-specific object

598
* to be used as the context

599
*

600
* @return a <code>Context</code> wrapper around the object

601
*/

602
protected Context getContext(Object node)

603
{

604 1625
if ( node instanceof Context )

605
{

606 1416
return (Context) node;

607
}

608

609 209
Context fullContext = new Context( getContextSupport() );

610

611 209
if ( node instanceof List )

612
{

613 1
fullContext.setNodeSet( (List) node );

614
}

615
else

616
{

617 208
List list = new SingletonList(node);

618 208
fullContext.setNodeSet( list );

619
}

620

621 209
return fullContext;

622
}

623

624
/** Retrieve the {@link ContextSupport} aggregation of

625
* <code>NamespaceContext</code>, <code>FunctionContext</code>,

626
* <code>VariableContext</code>, and {@link Navigator}.

627
*

628
* @return aggregate <code>ContextSupport</code> for this

629
* XPath expression

630
*/

631
protected ContextSupport getContextSupport()

632
{

633 297
if ( support == null )

634
{

635 236
support = new ContextSupport(

636
createNamespaceContext(),

637
createFunctionContext(),

638
createVariableContext(),

639
getNavigator()

640
);

641
}

642

643 297
return support;

644
}

645

646
/** Retrieve the XML object-model-specific {@link Navigator}

647
* for us in evaluating this XPath expression.

648
*

649
* @return the implementation-specific <code>Navigator</code>

650
*/

651
public Navigator getNavigator()

652
{

653 236
return navigator;

654
}

655

656

657

658
// ------------------------------------------------------------

659
// ------------------------------------------------------------

660
// Factory methods for default contexts

661
// ------------------------------------------------------------

662
// ------------------------------------------------------------

663

664
/** Create a default <code>FunctionContext</code>.

665
*

666
* @return a default <code>FunctionContext</code>

667
*/

668
protected FunctionContext createFunctionContext()

669
{

670 236
return XPathFunctionContext.getInstance();

671
}

672

673
/** Create a default <code>NamespaceContext</code>.

674
*

675
* @return a default <code>NamespaceContext</code> instance

676
*/

677
protected NamespaceContext createNamespaceContext()

678
{

679 236
return new SimpleNamespaceContext();

680
}

681

682
/** Create a default <code>VariableContext</code>.

683
*

684
* @return a default <code>VariableContext</code> instance

685
*/

686
protected VariableContext createVariableContext()

687
{

688 236
return new SimpleVariableContext();

689
}

690

691
/** Select all nodes that match this XPath

692
* expression on the given Context object.

693
* If multiple nodes match, multiple nodes

694
* will be returned in document-order, as defined by the XPath

695
* specification.

696
* 

697
*

698
* @param context the Context which gets evaluated

699
*

700
* @return the node-set of all items selected

701
* by this XPath expression

702
* @throws JaxenException if an XPath error occurs during expression evaluation

703
*

704
*/

705
protected List selectNodesForContext(Context context) throws JaxenException

706
{

707 1625
List list = this.xpath.asList( context );

708 1578
return list;

709

710
}

711

712

713
/** Return only the first node that is selected by this XPath

714
* expression. If multiple nodes match, only one node will be

715
* returned. The selected node will be the first

716
* selected node in document-order, as defined by the XPath

717
* specification.

718
* 

719
*

720
* @param context the Context against which this expression is evaluated

721
*

722
* @return the first node in document order of all nodes selected

723
* by this XPath expression; can this return a non-node????

724
* @throws JaxenException if an XPath error occurs during expression evaluation

725
*

726
* @see #selectNodesForContext

727
*/

728
protected Object selectSingleNodeForContext(Context context) throws JaxenException

729
{

730 6
List results = selectNodesForContext( context );

731

732 6
if ( results.isEmpty() )

733
{

734 2
return null;

735
}

736

737 4
return results.get( 0 );

738
}

739

740
}