| 1 |
x2j.go - Unmarshal arbitrary XML docs to map[string]interface{} or JSON and extract values (using wildcards, if necessary). |
| 2 |
|
| 3 |
NOTICE: |
| 4 |
|
| 5 |
26mar18: This is provided to aid transitioning applications using the "x2j" package to the "mxj" package. |
| 6 |
|
| 7 |
USAGE |
| 8 |
|
| 9 |
The package is fairly well self-documented. (http://godoc.org/github.com/clbanning/x2j) |
| 10 |
The one really useful function is: |
| 11 |
|
| 12 |
- Unmarshal(doc []byte, v interface{}) error |
| 13 |
where v is a pointer to a variable of type 'map[string]interface{}', 'string', or |
| 14 |
any other type supported by xml.Unmarshal(). |
| 15 |
|
| 16 |
To retrieve a value for specific tag use: |
| 17 |
|
| 18 |
- DocValue(doc, path string, attrs ...string) (interface{},error) |
| 19 |
- MapValue(m map[string]interface{}, path string, attr map[string]interface{}, recast ...bool) (interface{}, error) |
| 20 |
|
| 21 |
The 'path' argument is a period-separated tag hierarchy - also known as dot-notation. |
| 22 |
It is the program's responsibility to cast the returned value to the proper type; possible |
| 23 |
types are the normal JSON unmarshaling types: string, float64, bool, []interface, map[string]interface{}. |
| 24 |
|
| 25 |
To retrieve all values associated with a tag occurring anywhere in the XML document use: |
| 26 |
|
| 27 |
- ValuesForTag(doc, tag string) ([]interface{}, error) |
| 28 |
- ValuesForKey(m map[string]interface{}, key string) []interface{} |
| 29 |
|
| 30 |
Demos: http://play.golang.org/p/m8zP-cpk0O |
| 31 |
http://play.golang.org/p/cIteTS1iSg |
| 32 |
http://play.golang.org/p/vd8pMiI21b |
| 33 |
|
| 34 |
Returned values should be one of map[string]interface, []interface{}, or string. |
| 35 |
|
| 36 |
All the values assocated with a tag-path that may include one or more wildcard characters - |
| 37 |
'*' - can also be retrieved using: |
| 38 |
|
| 39 |
- ValuesFromTagPath(doc, path string, getAttrs ...bool) ([]interface{}, error) |
| 40 |
- ValuesFromKeyPath(map[string]interface{}, path string, getAttrs ...bool) []interface{} |
| 41 |
|
| 42 |
Demos: http://play.golang.org/p/kUQnZ8VuhS |
| 43 |
http://play.golang.org/p/l1aMHYtz7G |
| 44 |
|
| 45 |
NOTE: care should be taken when using "*" at the end of a path - i.e., "books.book.*". See |
| 46 |
the x2jpath_test.go case on how the wildcard returns all key values and collapses list values; |
| 47 |
the same message structure can load a []interface{} or a map[string]interface{} (or an interface{}) |
| 48 |
value for a tag. |
| 49 |
|
| 50 |
See the test cases in "x2jpath_test.go" and programs in "example" subdirectory for more. |
| 51 |
|
| 52 |
XML PARSING CONVENTIONS |
| 53 |
|
| 54 |
- Attributes are parsed to map[string]interface{} values by prefixing a hyphen, '-', |
| 55 |
to the attribute label. [See https://godoc.org/github.com/clbanning/mxj#SetAttrPrefix for options.] |
| 56 |
- If the element is a simple element and has attributes, the element value |
| 57 |
is given the key '#text' for its map[string]interface{} representation. (See |
| 58 |
the 'atomFeedString.xml' test data, below.) |
| 59 |
|
| 60 |
BULK PROCESSING OF MESSAGE FILES |
| 61 |
|
| 62 |
Sometime messages may be logged into files for transmission via FTP (e.g.) and subsequent |
| 63 |
processing. You can use the bulk XML message processor to convert files of XML messages into |
| 64 |
map[string]interface{} values with custom processing and error handler functions. See |
| 65 |
the notes and test code for: |
| 66 |
|
| 67 |
- XmlMsgsFromFile(fname string, phandler func(map[string]interface{}) bool, ehandler func(error) bool,recast ...bool) error |
| 68 |
[See https://godoc.org/github.com/clbanning/mxj#HandleXmlReader for general version.] |
| 69 |
|
| 70 |
IMPLEMENTATION NOTES |
| 71 |
|
| 72 |
Nothing fancy here, just brute force. |
| 73 |
|
| 74 |
- Use xml.Decoder to parse the XML doc and build a tree. |
| 75 |
- Walk the tree and load values into a map[string]interface{} variable, 'm', as |
| 76 |
appropriate. |
| 77 |
- Use json.Marshaler to convert 'm' to JSON. |
| 78 |
|
| 79 |
As for testing: |
| 80 |
|
| 81 |
- Copy an XML doc into 'x2j_test.xml'. |
| 82 |
- Run "go test" and you'll get a full dump. |
| 83 |
("pathTestString.xml" and "atomFeedString.xml" are test data from "read_test.go" |
| 84 |
in the encoding/xml directory of the standard package library.) |
| 85 |
|
| 86 |
MOTIVATION |
| 87 |
|
| 88 |
I make extensive use of JSON for messaging and typically unmarshal the messages into |
| 89 |
map[string]interface{} variables. This is easily done using json.Unmarshal from the |
| 90 |
standard Go libraries. Unfortunately, many legacy solutions use structured |
| 91 |
XML messages; in those environments the applications would have to be refitted to |
| 92 |
interoperate with my components. |
| 93 |
|
| 94 |
The better solution is to just provide an alternative HTTP handler that receives |
| 95 |
XML doc messages and parses it into a map[string]interface{} variable and then reuse |
| 96 |
all the JSON-based code. The Go xml.Unmarshal() function does not provide the same |
| 97 |
option of unmarshaling XML messages into map[string]interface{} variables. So I wrote |
| 98 |
a couple of small functions to fill this gap. |
| 99 |
|
| 100 |
Of course, once the XML doc was unmarshal'd into a map[string]interface{} variable it |
| 101 |
was just a matter of calling json.Marshal() to provide it as a JSON string. Hence 'x2j' |
| 102 |
rather than just 'x2m'. |
| 103 |
|
| 104 |
USES |
| 105 |
|
| 106 |
- putting a XML API on our message hub middleware (http://jsonhub.net) |
| 107 |
- loading XML data into NoSQL database, such as, mongoDB |
| 108 |
|
| 109 |
|