Context (element-path-finder 1.0-SNAPSHOT API)

All Known Subinterfaces:

MutableContext

All Known Implementing Classes:

MutableJsonContext
```
public interface Context
```
This API is meant to make it easier to search disparate data formats (e.g. XML, JSON), by acting as a wrapper around those data structures to provide a consistent API to query the data, whih allows decoupling an application from the data format that it acts on.. The data structures that it wraps may be hierarchical in nature, in which case recursion can be applied. However, such implementation details are left up to implementing classes to handle according to the characteristics of the data structure they intend to support. The main main motivation of this API is to keep client code decoupled from the details of the underlying format of the data, be it JSON, XML and the like. The only coupling/contract is done via input arguments to the various methods provided by this API. The only pain point is that the input parameters must be properly configured before this method gets invoked, but that's a small price to pay in comparison to the maintainability and re-usability that is achieved via the use of this API. The input parameters to search a Context object can be compared to the XPath syntax, which is used to navigate the elements and attribute of an XML document. Only difference here is that this API is not married to any specific format. All the operations provided by this interface are read-only, which essentially renders the Context object immutable after its creation. Created by QuijadaJ on 5/3/2017.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`FOUND_ELEM_VAL_IS_REGEX`
`static String`	`IGNORE_INCOMPATIBLE_SEARCH_PATH_PROVIDED_ERROR`
`static String`	`IGNORE_INCOMPATIBLE_TARGET_ELEMENT_PROVIDED_ERROR`
`static String`	`PARTIAL_REGEX_MATCH`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`boolean`	`arrayContains(String pVal)` When the `Context` is an array, checks if the value is contained in it.
`List<Context>`	`asArray()` Meant for use only `isArray()` is true, will return a `List` of the underlying array-like structure.
`boolean`	`containsElement(String pElemName)` To be used only when the underlying data is complex, returns true if underlying data contains the `pElemName` given
`Context`	`entryFromArray(int pIdx)` If the underlying data is array-like, will retrieve entry at index `pIdx`
`Set<Map.Entry<String,Context>>`	`entrySet()` To be used only when the underlying data is complex, returns a `Set` of `Map.Entry`s to represent the name/value pairs contained int he complex data structure.
`SearchResult`	`findElement(SearchPath pSearchPath, Filter pFilter, TargetElements pTargetElements, Map<String,String> pExtraParams)` Represents the entry point to begin searching the underlying data structure.
`SearchResult`	`findElement(SelectionCriteria pSelectCriteria, Map<String,String> pExtraParams)` Works similar to `findElement(SearchPath, Filter, TargetElements, Map)`, except that the first three arguments are replaced with a `SelectionCriteria` element.
`boolean`	`isArray()` Implementing classes use this method to tell if underlying data is a type of array or list-like.
`boolean`	`isPrimitive()` Implementing classes use this method to tell if underlying data is a primitive (I.e.
`boolean`	`isRecursible()` Implementing classes use this method to tell if underlying data is complex (I.e.
`Context`	`memberValue(String pMemberName)` To be used only when the underlying data is complex, returns the value of the specified `pMemberName`
`SearchPath`	`startSearchPath()` Gives the starting search path of this `Context`.
`String`	`stringRepresentation()` If the underlying data provides implementation aside from the toString() to return the data as a string, then this method is expected to wrap such an implmentation.
`List<String>`	`topLevelElementNames()` This method is applicable for `Context`'s that return `true` when `isRecursible()` gets invoked.
`static <T extends String> List<T>`	`transformArgumentToListObject(T pArg)` Utility method which attempts to transform passed in argument to a `List`.

- Field Detail
  - FOUND_ELEM_VAL_IS_REGEX
```
static final String FOUND_ELEM_VAL_IS_REGEX
```
    See Also:
    
    Constant Field Values
  - PARTIAL_REGEX_MATCH
```
static final String PARTIAL_REGEX_MATCH
```
    See Also:
    
    Constant Field Values
  - IGNORE_INCOMPATIBLE_SEARCH_PATH_PROVIDED_ERROR
```
static final String IGNORE_INCOMPATIBLE_SEARCH_PATH_PROVIDED_ERROR
```
    See Also:
    
    Constant Field Values
  - IGNORE_INCOMPATIBLE_TARGET_ELEMENT_PROVIDED_ERROR
```
static final String IGNORE_INCOMPATIBLE_TARGET_ELEMENT_PROVIDED_ERROR
```
    See Also:
    
    Constant Field Values
- Method Detail
  - findElement
```
SearchResult findElement(SearchPath pSearchPath,
                         Filter pFilter,
                         TargetElements pTargetElements,
                         Map<String,String> pExtraParams)
                  throws IllegalArgumentException
```
    Represents the entry point to begin searching the underlying data structure. The search works by specifying a path to the node of interest, represented by a SearchPath. The Context object off of which this method can be invoked was previously obtained via a call to factory method ContextFactory.obtainContext(Object). To further refine the results use the pFilter and pTargetElements arguments. TODO: Add more examples of usage
    
    Parameters:
    
    pSearchPath - - The path that in the underlying data structure that this method has been instructed to find. For more information on how to build a SearchPath object to then pass it here, read the documentation of SearchPath.valueOf(String). Basically the last node of the SearchPath is what gets returned to the caller. This can be a primitive, and array (of primitives, or other complex structures, or a combination thereof), or a complex data structure. The type of the found element determines how the pFilter and pTargetElements arguments behave. Read respective description of these arguments for more details. If an array element will be encountered somewhere in the search path, then the corresponding node should contain square brackets like this: someElemName[0]. If an array element is encountered yet the path did not tell this method to expect an array at this point (by appending "[N]" to the path node), IllegalArgumentException is thrown, *unless* the array element happens to be the last node of the search path.
    
    pFilter - - Use this argument to further refine the search rules. Build a filter by specifying a semi-colon separated list of name/value pairs separated by equals sign, and pass that string to factory method Filter.valueOf(String), like this: Filter.valueOf("name1=val1;name2=val2") The keys specified should correspond to keys found in the last node of the pSearchPath. This assumes that developer is intimately familiar with the data structure he's working with, and that he'll know exactly what result pSearchPath will yield. How pFilter gets applied depends on the type of data found in the last node of the pSearchPath. In all cases, the members of the search results are checked to see if a corresponding key is found in the Filter specified, and if so that member value is compared against the filter value. The filter values can have wildcards too. There can be a wildcard at either the beginning, the end or both. Below lists the possible types of data that can be found at end of search path, and how the filter gets applied in each case: primitive: simply compare the corresponding filter value against the primitive, and if there's a match that primitive will be included in the search result array: Primitive entries are handled the same way single primitive results are found. Complex structures in the array have their members checked against the filter the same way single complex structures are handled as described below. complex structure: Each member of the complex structure is checked to see if there's a filter value provided. If there's a match, then this complex structure will be included in the results. A Filter key can be a search path also, in which case the value for the filter search path is found relative to the last node of the search path passed to this method. An error is thrown if the filter search path is not found, otherwise the node will be included in the search results if the filter value matches the value found in the underlying Context. An example of a filter that has a search path as key is: SearchPath: top_node.inner_node.member2 Filter: key=sub_member5.key=1234 Context (assuming underlying data is in JSON format): { "top_node":{ "inner_node":{ "member1":1110, "member2":[ { "sub_member_1":1110, "sub_member_2":15199, "sub_member_3":13135, "sub_member_4":7184441216, "sub_member5": { "key": "abcd" } }, { "sub_member_1":1110, "sub_member_2":15199, "sub_member_3":24099, "sub_member_4":7184441216, "sub_member5": { "key": "1234" } } ], "member3":1073, "member4":7184441216, "member5":19555 } } } Based on the filter, the second entry of the "member2" array could be selected. TODO: Filter key values also support passing in a comma separated list of values
    
    pTargetElements - - Use it to further refine the search results by specifying which elements to return in the search results when the last node of the pSearchPath yields a complex data structure, and you're only interested in a sub-set of the members of the found complex data structure.
    
    pExtraParams - - Implementing classes can use this Map to provide arbitrary list of name/value pairs to provide features/behavior that this interface does not already plan for. TODO: Clearly document *all* keys supported; they're defined as constants at top of this class
    
    Returns:
    
    - A SearchResult which is nothing more than a Map that maps keys to Context objects. Each Context object in the SearchResult can be a primitive, or an array, or another complex object. Refer to the other methods of this class for the available operations.
    
    Throws:
    
    IllegalArgumentException - - Thrown if parameter pSearchPath is determined to be invalid for whatever reason.
  - findElement
```
SearchResult findElement(SelectionCriteria pSelectCriteria,
                         Map<String,String> pExtraParams)
                  throws IllegalArgumentException
```
    Works similar to findElement(SearchPath, Filter, TargetElements, Map), except that the first three arguments are replaced with a SelectionCriteria element.
    
    Parameters:
    
    pSelectCriteria - - pSelectCriteria
    
    pExtraParams - - pExtraParams
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalArgumentException - - TODO
  - isPrimitive
```
boolean isPrimitive()
```
    Implementing classes use this method to tell if underlying data is a primitive (I.e. long, int, double, String, etc...
    
    Returns:
    
    - TODO
  - isRecursible
```
boolean isRecursible()
```
    Implementing classes use this method to tell if underlying data is complex (I.e. not a primitive).
    
    Returns:
    
    - TODO
  - isArray
```
boolean isArray()
```
    Implementing classes use this method to tell if underlying data is a type of array or list-like.
    
    Returns:
    
    - TODO
  - asArray
```
List<Context> asArray()
               throws IllegalStateException
```
    Meant for use only isArray() is true, will return a List of the underlying array-like structure.
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - entryFromArray
```
Context entryFromArray(int pIdx)
                throws IllegalStateException
```
    If the underlying data is array-like, will retrieve entry at index pIdx
    
    Parameters:
    
    pIdx - - pIdx
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - stringRepresentation
```
String stringRepresentation()
```
    If the underlying data provides implementation aside from the toString() to return the data as a string, then this method is expected to wrap such an implmentation.
    
    Returns:
    
    - TODO
  - containsElement
```
boolean containsElement(String pElemName)
                 throws IllegalStateException
```
    To be used only when the underlying data is complex, returns true if underlying data contains the pElemName given
    
    Parameters:
    
    pElemName - - pElemName
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - entrySet
```
Set<Map.Entry<String,Context>> entrySet()
                                 throws IllegalStateException
```
    To be used only when the underlying data is complex, returns a Set of Map.Entrys to represent the name/value pairs contained int he complex data structure.
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - memberValue
```
Context memberValue(String pMemberName)
             throws IllegalStateException
```
    To be used only when the underlying data is complex, returns the value of the specified pMemberName
    
    Parameters:
    
    pMemberName - - pMemberName
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - arrayContains
```
boolean arrayContains(String pVal)
               throws IllegalStateException
```
    When the Context is an array, checks if the value is contained in it.
    
    Parameters:
    
    pVal - - pVal
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - startSearchPath
```
SearchPath startSearchPath()
```
    Gives the starting search path of this Context. This works only when the data is recursible (isRecursible() yields true), and there's only one outer most element, else this method returns null. This was added mainly as a convenience so that calling code does not need to be calculating this value over and over again. There's no reason the Context object itself can't provide this information.
    
    Returns:
    
    - The starting SearchPath if there's just a single outermost element, null otherwise.
  - topLevelElementNames
```
List<String> topLevelElementNames()
```
    This method is applicable for Context's that return true when isRecursible() gets invoked.
    
    Returns:
    
    - A list of what the top level field names are for this recursible Context. If this Context is not recursible, then null is returned.
  - transformArgumentToListObject
```
static <T extends String> List<T> transformArgumentToListObject(T pArg)
```
    Utility method which attempts to transform passed in argument to a List. Argument must be a String object or a sub-type, and must be a comma-separated list of values, or a value that ContextFactory.obtainContext(Object) can transform to an array of primitives (for example a string like '[a,b,c,d]' is recognized as JSON, hence can be transformed to Context by ContextFactory.obtainContext(Object) because JSON is one the formats recognized by that factory).
    
    Type Parameters:
    
    T - - T
    
    Parameters:
    
    pArg - - What will get transformed to a List of String's, if possible.
    
    Returns:
    
    - The List of String's produced, if possible, null otherwise

Interface Context

Field Summary

Method Summary

Field Detail

FOUND_ELEM_VAL_IS_REGEX

PARTIAL_REGEX_MATCH

IGNORE_INCOMPATIBLE_SEARCH_PATH_PROVIDED_ERROR

IGNORE_INCOMPATIBLE_TARGET_ELEMENT_PROVIDED_ERROR

Method Detail

findElement

findElement

isPrimitive

isRecursible

isArray

asArray

entryFromArray

stringRepresentation

containsElement

entrySet

memberValue

arrayContains

startSearchPath

topLevelElementNames

transformArgumentToListObject