Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 169 lines (130 sloc) 6.939 kb
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
1 # Oj gem
2 A fast JSON parser and Object marshaller as a Ruby gem.
3
4 ## <a name="installation">Installation</a>
5 gem install oj
6
7 ## <a name="source">Source</a>
8
9 *GitHub* *repo*: https://github.com/ohler55/oj
10
11 *RubyGems* *repo*: https://rubygems.org/gems/oj
12
13 ## <a name="build_status">Build Status</a>
14
da0330c4 » Peter Ohler
2012-02-19 getting the travis image to show status
15 [![Build Status](https://secure.travis-ci.org/ohler55/oj.png?branch=master)](http://travis-ci.org/ohler55/oj)
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
16
17 ## <a name="links">Links of Interest</a>
18
afe4e992 » Peter Ohler
2012-02-25 changed json object format
19 *Fast XML parser and marshaller on RubyGems*: https://rubygems.org/gems/ox
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
20
afe4e992 » Peter Ohler
2012-02-25 changed json object format
21 *Fast XML parser and marshaller on GitHub*: https://rubygems.org/gems/ox
57afd74e » Peter Ohler
2012-02-19 fixed a few bugs and added options
22
afe4e992 » Peter Ohler
2012-02-25 changed json object format
23 ## <a name="release">Release Notes</a>
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
24
afe4e992 » Peter Ohler
2012-02-25 changed json object format
25 ### Release 0.7.0
8711c855 » Peter Ohler
2012-02-22 serializes any Object now. Tests added as well.
26
afe4e992 » Peter Ohler
2012-02-25 changed json object format
27 - changed the object JSON format
8711c855 » Peter Ohler
2012-02-22 serializes any Object now. Tests added as well.
28
afe4e992 » Peter Ohler
2012-02-25 changed json object format
29 - serialized Ruby Objects can now be deserialized
8711c855 » Peter Ohler
2012-02-22 serializes any Object now. Tests added as well.
30
afe4e992 » Peter Ohler
2012-02-25 changed json object format
31 - improved performance testing
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
32
33 ## <a name="description">Description</a>
34
35 Optimized JSON (Oj), as the name implies was written to provide speed
36 optimized JSON handling. It was designed as a faster alternative to Yajl and
37 other the common Ruby JSON parsers. So far is has achieved that at about 2
38 time faster than Yajl for parsing and 3 or more times faster writing JSON.
39
8711c855 » Peter Ohler
2012-02-22 serializes any Object now. Tests added as well.
40 Oj has several dump or serialization modes which control how Objects are
41 converted to JSON. These modes are set with the :effort option in either the
42 dafault options or as one of the options to the dump() method. The :strict
43 mode will only allow the 7 basic JSON types to be serialized. Any other Object
44 will raise and Exception. In the :lazy mode any Object that is not one of the
45 JSON types is replaced by a JSON null. In :interal mode any Object will be
46 dumped as a JSON Object with keys that match the Ruby Object's variable names
47 without the '@' character. This is the highest performance mode. The :internal
48 mode is not found in other JSON gems. The last mode, the :tolerant mode is the
49 most tolerant. It will serialize any Object but will check to see if the
50 Object implements a to_hash() or to_json() method. If either exists that
51 method is used for serializing the Object. The to_hash() is more flexible and
52 produces more consistent output so it has a preference over the to_json()
53 method. If neither the to_json() or to_hash() methods exist then the Oj
54 internal Object variable encoding is used.
55
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
56 Coming soon: As an Object marshaller with support for circular references.
57
8711c855 » Peter Ohler
2012-02-22 serializes any Object now. Tests added as well.
58 Coming soon: A JSON stream parser.
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
59
60 Oj is compatible with Ruby 1.8.7, 1.9.2, 1.9.3, JRuby, and RBX.
61
66692066 » Peter Ohler
2012-02-22 ready for 0.6.0 release
62 ## <a name="compare">Comparisons</a>
63
64 The following table shows the difference is speeds between several
65 serialization packages. The tests had to be scaled back due to limitation of
66 some of the gems. I finally gave up trying to get JSON to serialize without
67 errors with Ruby 1.9.3. It had internal errors on anything other than a simple
68 JSON structure. The errors encountered were:
69
70 - MessagePack fails to convert Bignum to JSON
71
72 - JSON Pure and Ext fails to serialize any numbers or Objects with the to_json() method
73
74 Options were added to the test/perf_simple.rb test to run the test without
75 Object encoding and without Bignums. There is also an option for shallow JSON
76 so that JSON Pure and Ext can be compared.
77
78 None of the packages except Oj were able to serialize Ruby Objects that did
79 not have a to_json() method or were of the 7 native JSON types.
80
81 It is also worth noting that although Oj is slightly behind MessagePack for
82 parsing, Oj serialization is much faster than MessagePack even though Oj uses
83 human readable JSON vs the binary MessagePack format.
84
85 The results:
86
87 with Object and Bignum encoding:
88
89 100000 Oj.load()s in 1.456 seconds or 68.7 loads/msec
90 100000 Yajl::Parser.parse()s in 2.681 seconds or 37.3 parses/msec
91 100000 JSON::Ext::Parser parse()s in 2.804 seconds or 35.7 parses/msec
92 100000 JSON::Pure::Parser parse()s in 27.494 seconds or 3.6 parses/msec
93 MessagePack failed: RangeError: bignum too big to convert into `unsigned long long'
94 100000 Ox.load()s in 3.165 seconds or 31.6 loads/msec
95 Parser results:
96 gem seconds parses/msec X faster than JSON::Pure (higher is better)
97 oj 1.456 68.7 18.9
98 yajl 2.681 37.3 10.3
99 msgpack failed to generate JSON
100 pure 27.494 3.6 1.0
101 ext 2.804 35.7 9.8
102 ox 3.165 31.6 8.7
103
104 100000 Oj.dump()s in 0.484 seconds or 206.7 dumps/msec
105 100000 Yajl::Encoder.encode()s in 2.167 seconds or 46.2 encodes/msec
106 JSON::Ext failed: TypeError: wrong argument type JSON::Pure::Generator::State (expected Data)
107 JSON::Pure failed: TypeError: wrong argument type JSON::Pure::Generator::State (expected Data)
108 MessagePack failed: RangeError: bignum too big to convert into `unsigned long long'
109 100000 Ox.dump()s in 0.554 seconds or 180.4 dumps/msec
110 Parser results:
111 gem seconds dumps/msec X faster than Yajl (higher is better)
112 oj 0.484 206.7 4.5
113 yajl 2.167 46.2 1.0
114 msgpack failed to generate JSON
115 pure failed to generate JSON
116 ext failed to generate JSON
117 ox 0.554 180.4 3.9
118
119 without Objects or numbers (for JSON Pure) JSON:
120
121 100000 Oj.load()s in 0.739 seconds or 135.3 loads/msec
122 100000 Yajl::Parser.parse()s in 1.421 seconds or 70.4 parses/msec
123 100000 JSON::Ext::Parser parse()s in 1.512 seconds or 66.2 parses/msec
124 100000 JSON::Pure::Parser parse()s in 16.953 seconds or 5.9 parses/msec
125 100000 MessagePack.unpack()s in 0.635 seconds or 157.6 packs/msec
126 100000 Ox.load()s in 0.971 seconds or 103.0 loads/msec
127 Parser results:
128 gem seconds parses/msec X faster than JSON::Pure (higher is better)
129 oj 0.739 135.3 22.9
130 yajl 1.421 70.4 11.9
131 msgpack 0.635 157.6 26.7
132 pure 16.953 5.9 1.0
133 ext 1.512 66.2 11.2
134 ox 0.971 103.0 17.5
135
136 100000 Oj.dump()s in 0.174 seconds or 575.1 dumps/msec
137 100000 Yajl::Encoder.encode()s in 0.729 seconds or 137.2 encodes/msec
138 100000 JSON::Ext generate()s in 7.171 seconds or 13.9 generates/msec
139 100000 JSON::Pure generate()s in 7.219 seconds or 13.9 generates/msec
140 100000 Msgpack()s in 0.299 seconds or 334.8 unpacks/msec
141 100000 Ox.dump()s in 0.210 seconds or 475.8 dumps/msec
142 Parser results:
143 gem seconds dumps/msec X faster than JSON::Pure (higher is better)
144 oj 0.174 575.1 41.5
145 yajl 0.729 137.2 9.9
146 msgpack 0.299 334.8 24.2
147 pure 7.219 13.9 1.0
148 ext 1.512 66.2 4.8
149 ox 0.210 475.8 34.3
150
6248665d » Peter Ohler
2012-02-19 ready for use with limitations
151 ### Simple JSON Writing and Parsing:
152
153 require 'oj'
154
155 h = { 'one' => 1, 'array' => [ true, false ] }
156 json = Oj.dump(h)
157
158 # json =
159 # {
160 # "one":1,
161 # "array":[
162 # true,
163 # false
164 # ]
165 # }
166
167 h2 = Oj.parse(json)
168 puts "Same? #{h == h2}"
169 # true
Something went wrong with that request. Please try again.