Debian Codegraph @

x2j-wrapper/README

raw
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