##### Coverage Report - org.apache.commons.configuration.tree.ExpressionEngine

Classes in this File | Line Coverage | Branch Coverage | Complexity

ExpressionEngine

N/A | N/A

N/A | N/A

1.0;1

1

     /*

2

      * Licensed to the Apache Software Foundation (ASF) under one or more

3

      * contributor license agreements.  See the NOTICE file distributed with

4

      * this work for additional information regarding copyright ownership.

5

      * The ASF licenses this file to You under the Apache License, Version 2.0

6

      * (the "License"); you may not use this file except in compliance with

7

      * the License.  You may obtain a copy of the License at

8

      *

9

      *     http://www.apache.org/licenses/LICENSE-2.0

10

      *

11

      * Unless required by applicable law or agreed to in writing, software

12

      * distributed under the License is distributed on an "AS IS" BASIS,

13

      * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

14

      * See the License for the specific language governing permissions and

15

      * limitations under the License.

16

      */

17

     package org.apache.commons.configuration.tree;

18

19

     import java.util.List;

20

21

     /**

22

      * <p>

23

      * Definition of an interface for evaluating keys for hierarchical

24

      * configurations.

25

      * </p>

26

      * <p>

27

      * An <em>expression engine</em> knows how to map a key for a configuration's

28

      * property to a single or a set of configuration nodes. Thus it defines the way

29

      * how properties are addressed in this configuration. Methods of a

30

      * configuration that have to handle property key (e.g.

31

      * <code>getProperty()</code> or <code>addProperty()</code> do not interpret

32

      * the passed in keys on their own, but delegate this task to an associated

33

      * expression engine. This expression engine will then find out, which

34

      * configuration nodes are addressed by the key.

35

      * </p>

36

      * <p>

37

      * Seperating the task of evaluating property keys from the configuration object

38

      * has the advantage that many different expression languages (i.e. ways for

39

      * querying or setting properties) can be supported. Just set a suitable

40

      * implementation of this interface as the configuration's expression engine,

41

      * and you can use the syntax provided by this implementation.

42

      * </p>

43

      *

44

      * @since 1.3

45

      * @author Oliver Heger

46

      */

47

     public interface ExpressionEngine

48

     {

49

         /**

50

          * Finds the node(s) that is (are) matched by the specified key. This is the

51

          * main method for interpreting property keys. An implementation must

52

          * traverse the given root node and its children to find all nodes that are

53

          * matched by the given key. If the key is not correct in the syntax

54

          * provided by that implementation, it is free to throw a (runtime)

55

          * exception indicating this error condition.

56

          *

57

          * @param root the root node of a hierarchy of configuration nodes

58

          * @param key the key to be evaluated

59

          * @return a list with the nodes that are matched by the key (should never

60

          * be <b>null</b>)

61

          */

62

         List query(ConfigurationNode root, String key);

63

64

         /**

65

          * Returns the key for the specified node in the expression language

66

          * supported by an implementation. This method is called whenever a property

67

          * key for a node has to be constructed, e.g. by the

68

          * <code>{@link org.apache.commons.configuration.Configuration#getKeys() getKeys()}</code>

69

          * method.

70

          *

71

          * @param node the node, for which the key must be constructed

72

          * @param parentKey the key of this node's parent (can be <b>null</b> for

73

          * the root node)

74

          * @return this node's key

75

          */

76

         String nodeKey(ConfigurationNode node, String parentKey);

77

78

         /**

79

          * Returns information needed for an add operation. This method gets called

80

          * when new properties are to be added to a configuration. An implementation

81

          * has to interpret the specified key, find the parent node for the new

82

          * elements, and provide all information about new nodes to be added.

83

          *

84

          * @param root the root node

85

          * @param key the key for the new property

86

          * @return an object with all information needed for the add operation

87

          */

88

         NodeAddData prepareAdd(ConfigurationNode root, String key);

89

     }