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

java.lang.Object
- com.exsoinn.util.epf.MutableJsonContext

All Implemented Interfaces:

Context, MutableContext
```
public class MutableJsonContext
extends Object
implements MutableContext
```
Created by QuijadaJ on 5/24/2017.

Field Summary
- Fields inherited from interface com.exsoinn.util.epf.Context
  FOUND_ELEM_VAL_IS_REGEX, IGNORE_INCOMPATIBLE_SEARCH_PATH_PROVIDED_ERROR, IGNORE_INCOMPATIBLE_TARGET_ELEMENT_PROVIDED_ERROR, PARTIAL_REGEX_MATCH

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addEntryToArray(Context pEntry)`
`void`	`addMember(String pName, Context pContext)`
`boolean`	`arrayContains(String pVal)` When the `Context` is an array, checks if the value is contained in it.
`List<Context>`	`asArray()` TODO: Can perhaps return unmodifiable list of the same JsonArray entries.
`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()` If this is a `JsonObject`, return an `Set` of `Map.Entry` of the members of this object.
`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 `Context.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 `Context.isRecursible()` gets invoked.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.exsoinn.util.epf.Context
arrayContains, asArray, containsElement, entryFromArray, entrySet, findElement, findElement, isArray, isPrimitive, isRecursible, memberValue, startSearchPath, stringRepresentation, topLevelElementNames, transformArgumentToListObject

- Method Detail
  - addMember
```
public void addMember(String pName,
                      Context pContext)
```
    Specified by:
    
    addMember in interface MutableContext
  - addEntryToArray
```
public void addEntryToArray(Context pEntry)
```
    Specified by:
    
    addEntryToArray in interface MutableContext
  - isPrimitive
```
public boolean isPrimitive()
```
    Description copied from interface: Context
    
    Implementing classes use this method to tell if underlying data is a primitive (I.e. long, int, double, String, etc...
    
    Returns:
    
    - TODO
  - isRecursible
```
public boolean isRecursible()
```
    Description copied from interface: Context
    
    Implementing classes use this method to tell if underlying data is complex (I.e. not a primitive).
    
    Returns:
    
    - TODO
  - isArray
```
public boolean isArray()
```
    Description copied from interface: Context
    
    Implementing classes use this method to tell if underlying data is a type of array or list-like.
    
    Returns:
    
    - TODO
  - entryFromArray
```
public Context entryFromArray(int pIdx)
                       throws IllegalStateException
```
    Description copied from interface: Context
    
    If the underlying data is array-like, will retrieve entry at index pIdx
    
    Parameters:
    
    pIdx - - pIdx
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - stringRepresentation
```
public String stringRepresentation()
```
    Description copied from interface: Context
    
    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
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - asArray
```
public List<Context> asArray()
                      throws IllegalStateException
```
    TODO: Can perhaps return unmodifiable list of the same JsonArray entries. Would need to overload TODO: constructor to pass flag that tells it not to generate a new JsonElement
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - containsElement
```
public boolean containsElement(String pElemName)
```
    Description copied from interface: Context
    
    To be used only when the underlying data is complex, returns true if underlying data contains the pElemName given
    
    Parameters:
    
    pElemName - - pElemName
    
    Returns:
    
    - TODO
  - entrySet
```
public Set<Map.Entry<String,Context>> entrySet()
                                        throws IllegalStateException
```
    If this is a JsonObject, return an Set of Map.Entry of the members of this object.
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - memberValue
```
public Context memberValue(String pMemberName)
                    throws IllegalStateException
```
    Description copied from interface: Context
    
    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
```
public boolean arrayContains(String pVal)
                      throws IllegalStateException
```
    Description copied from interface: Context
    
    When the Context is an array, checks if the value is contained in it.
    
    Parameters:
    
    pVal - - pVal
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalStateException - - TODO
  - findElement
```
public SearchResult findElement(SearchPath pSearchPath,
                                Filter pFilter,
                                TargetElements pTargetElements,
                                Map<String,String> pExtraParams)
                         throws IllegalArgumentException
```
    Description copied from interface: Context
    
    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
    
    Specified by:
    
    findElement in interface Context
    
    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
```
public SearchResult findElement(SelectionCriteria pSelectCriteria,
                                Map<String,String> pExtraParams)
                         throws IllegalArgumentException
```
    Description copied from interface: Context
    
    Works similar to Context.findElement(SearchPath, Filter, TargetElements, Map), except that the first three arguments are replaced with a SelectionCriteria element.
    
    Specified by:
    
    findElement in interface Context
    
    Parameters:
    
    pSelectCriteria - - pSelectCriteria
    
    pExtraParams - - pExtraParams
    
    Returns:
    
    - TODO
    
    Throws:
    
    IllegalArgumentException - - TODO
  - startSearchPath
```
public SearchPath startSearchPath()
```
    Description copied from interface: Context
    
    Gives the starting search path of this Context. This works only when the data is recursible (Context.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.
    
    Specified by:
    
    startSearchPath in interface Context
    
    Returns:
    
    - The starting SearchPath if there's just a single outermost element, null otherwise.
  - topLevelElementNames
```
public List<String> topLevelElementNames()
```
    Description copied from interface: Context
    
    This method is applicable for Context's that return true when Context.isRecursible() gets invoked.
    
    Specified by:
    
    topLevelElementNames in interface Context
    
    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.

Class MutableJsonContext

Field Summary

Fields inherited from interface com.exsoinn.util.epf.Context

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.exsoinn.util.epf.Context

Method Detail

addMember

addEntryToArray

isPrimitive

isRecursible

isArray

entryFromArray

stringRepresentation

toString

asArray

containsElement

entrySet

memberValue

arrayContains

findElement

findElement

startSearchPath

topLevelElementNames