Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 108 lines (89 sloc) 3.17 kB
d910fca @kohanyirobert Initial commit.
kohanyirobert authored
1 # ebson
6115dbb @kohanyirobert Tweak README formatting.
kohanyirobert authored
2 *ebson* is an extensible [BSON][] encoder/decoder library written in Java. The
d910fca @kohanyirobert Initial commit.
kohanyirobert authored
3 library is extensible in the sense that the mappings between Java and BSON types
4 are configurable and the logic to serialize custom Java types is pluggable. Its
5 single dependency is the [Guava libraries][] by Google.
6
7 ## License
8 Released under the permissive [MIT License][].
9
10 ## Author
11 [Kohányi Róbert][].
12
13 ## Download
14 Add the library as a dependency in your project's *pom.xml* like this.
15
16 ```xml
17 <dependency>
18 <groupId>com.github.kohanyirobert</groupId>
19 <artifactId>ebson</artifactId>
20 <version>...</version>
21 </dependency>
22 ```
23
24 Releases and snapshots are deployed to [Sonatype's][] [OSS repository][] (and
25 synced to the [Central Maven Repository][] from there). To download JARs from
26 Sonatype's repository include the following repository tag inside your Maven
27 installation's *settings.xml* or your project's *pom.xml*.
28
29 ```xml
30 <repository>
31 <id>sonatype-oss<id>
32 <url>https://oss.sonatype.org/content/groups/public</url>
33 </repository>
34 ```
35
36 ## Build
37 As the project is managed with [Maven][] you simply clone it and issue *mvn
38 install* or *mvn package* inside the clone's directory.
39
40 ```
41 git clone git://github.com/kohanyirobert/ebson.git
42 cd ebson/
43 mvn package
44 # and/or
45 mvn install
46 ```
47
48 ## Usage
49 ### Serialization
50 ```java
51 // create documents to serialize
52 BsonDocument document = BsonDocuments.of("key", new Date());
53
54 // grab a little-endian byte buffer
55 ByteBuffer buffer = ByteBuffer.allocate(32).order(ByteOrder.LITTLE_ENDIAN);
56
57 // use the documents utility class to write the document into the buffer
58 BsonDocuments.writeTo(buffer, document);
59
60 // use the serialized data
61 buffer.flip();
62 ```
63
64 ### Deserialization
65 ```java
66 // given the previous buffer
67 BsonDocument newDocument = BsonDocuments.readFrom(buffer);
68
69 // prints true
70 System.out.println(document.equals(newDocument));
71 ```
72
73 ### Extensibility
74 ```java
75 // to use joda-time's date-time instead of java's date supply
76 // a predicate (to test whether an input class is compatible with
77 // date-time or not) for the appropriate bson type
78 BsonObject.UTC_DATE_TIME.predicate(new Predicate<Class<?>>() {
79 @Override public boolean apply(Class<?> input) {
80 return input == null ? false : DateTime.class.isAssignableFrom(input);
81 }
82 });
83
84 // register a writer with the same bson type which is
85 // able to serialize date-times into byte buffers
86 BsonObject.UTC_DATE_TIME.writer(new BsonWriter() {
87 @Override public void writeTo(ByteBuffer buffer, Object reference) {
88 buffer.putLong(((DateTime) reference).getMillis());
89 }
90 });
91
92 // finally register a reader to do all this ass backwards
93 BsonObject.UTC_DATE_TIME.reader(new BsonReader() {
94 @Override public Object readFrom(ByteBuffer buffer) {
95 return new DateTime(buffer.getLong());
96 }
97 });
98 ```
99
100 [BSON]: http://bsonspec.org
101 [Guava libraries]: http://code.google.com/p/guava-libraries
102 [Kohányi Róbert]: http://kohanyirobert.github.com
103 [MIT License]: https://raw.github.com/kohanyirobert/ebson/master/LICENSE.txt
104 [Sonatype's]: http://sonatype.com
105 [OSS repository]: https://oss.sonatype.org
106 [Central Maven Repository]: http://search.maven.org
107 [Maven]: http://maven.apache.org
Something went wrong with that request. Please try again.