This repository was archived by the owner on Oct 4, 2018. It is now read-only.
forked from SQiShER/java-object-diff
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
131 lines (100 loc) · 9.29 KB
/
index.html
File metadata and controls
131 lines (100 loc) · 9.29 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<link href='https://fonts.googleapis.com/css?family=Architects+Daughter' rel='stylesheet' type='text/css'>
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<title>java-object-diff by SQiShER</title>
</head>
<body>
<header>
<div class="inner">
<h1>java-object-diff</h1>
<h2>Framework to diff and merge Java objects</h2>
<a href="https://github.com/SQiShER/java-object-diff" class="button"><small>View project on</small>GitHub</a>
</div>
</header>
<div id="content-wrapper">
<div class="inner clearfix">
<section id="main-content">
<h2>
<a name="introduction" class="anchor" href="#introduction"><span class="octicon octicon-link"></span></a>Introduction</h2>
<p><code>java-object-diff</code> is a simple, yet powerful library to find differences between Java objects. It takes two objects and generates a tree structure that represents any differences between the objects and their children. This tree can then be traversed to extract more information or apply changes to the underlying data structures.</p>
<p><a href="https://travis-ci.org/SQiShER/java-object-diff"><img src="https://travis-ci.org/SQiShER/java-object-diff.svg?branch=master" alt="Build Status"></a></p>
<h2>
<a name="features" class="anchor" href="#features"><span class="octicon octicon-link"></span></a>Features</h2>
<ul>
<li>Generates an easily traversable tree structure to analyze and modify with surgical precision</li>
<li>Detects whether a value or item has been added, removed or changed and shows the changes</li>
<li>Allows to manipulate the underlying objects directly through the generated tree nodes</li>
<li>Works with almost any kind of object (Beans, Lists, Maps, Primitives, Strings, etc.)</li>
<li>Properties can be marked with category tags to easily filter for specific subsets</li>
<li>No configuration needed (but possible)</li>
<li>No runtime dependencies except for <a href="http://www.slf4j.org/">SLF4J</a>
</li>
<li>When needed, it leaves it up to you, whether you want to use declarative configuration or annotations</li>
</ul><h2>
<a name="getting-started" class="anchor" href="#getting-started"><span class="octicon octicon-link"></span></a>Getting Started</h2>
<p>To learn how to use <strong>Java Object Diff</strong>, please have a look at the <a href="https://github.com/SQiShER/java-object-diff/wiki/Getting-Started">Starter Guide</a>.</p>
<h2>
<a name="why-would-you-need-this" class="anchor" href="#why-would-you-need-this"><span class="octicon octicon-link"></span></a>Why would you need this?</h2>
<p>Sometimes you need to figure out, how one version of an object differs from another one. One of the simplest solutions that'll cross your mind is most certainly to use reflection to scan the object for fields or getters and use them to compare the values of the different object instances. In many cases this is a perfectly valid strategy and the way to go. After all, we want to keep things simple, don't we?</p>
<p>However, there are some cases that can increase the complexity dramatically. What if you need to find differences in collections or maps? What if you have to deal with nested objects that also need to be compared on a per-property basis? Or even worse: what if you need to merge such objects?</p>
<p>You suddenly realize that you need to scan the objects recursively, figure out which collection items have been added, removed or changed; find a way to return your results in a way that allows you to easily access the information you are looking for and provide accessors to apply changes.</p>
<p>While all this isn't exactly rocket science, it is complex enough to add quite a lot of extra code to your project. Code that needs to be tested and maintained. Since the best code is the code you didn't write, this library aims to help you with all things related to diffing and merging of Java objects by providing a robust foundation and a simple, yet powerful API.</p>
<p>This library will hide all the complexities of deep object comparison behind one line of code:</p>
<div class="highlight highlight-java"><pre><span class="n">Node</span> <span class="n">root</span> <span class="o">=</span> <span class="n">ObjectDifferFactory</span><span class="o">.</span><span class="na">getInstance</span><span class="o">().</span><span class="na">compare</span><span class="o">(</span><span class="n">workingObject</span><span class="o">,</span> <span class="n">baseObject</span><span class="o">);</span>
</pre></div>
<p>This generates a tree structure of the given object type and lets you traverse its nodes via visitors. Each node represents one property (or collection item) of the underlying object and tells you exactly if and how the value differs from the base version. It also provides accessors to read, write and remove the value from or to any given instance. This way, all you need to worry about is <strong>how to treat</strong> changes and <strong>not how to find</strong> them.</p>
<p>This library has been battle-tested in a rather big project of mine, where I use it to generate <strong>activity streams</strong>, resolve database <strong>update conflics</strong>, display <strong>change logs</strong> and limit the scope of entity updates to only a <strong>subset of properties</strong>, based on the context or user permissions. It didn't let me down so far and I hope that it can help you too!</p>
<h2>
<a name="use-cases" class="anchor" href="#use-cases"><span class="octicon octicon-link"></span></a>Use Cases</h2>
<p><strong>Java Object Diff</strong> is currently used (but not limited) to...</p>
<ul>
<li>Generate Facebook-like activity streams</li>
<li>Visualize the differences between object versions</li>
<li>Automatically resolve conflicts on concurrent database updates</li>
<li>Detect and persist only properties that were actually changed</li>
</ul><h2>
<a name="contribute" class="anchor" href="#contribute"><span class="octicon octicon-link"></span></a>Contribute</h2>
<p>You discovered a bug or have an idea for a new feature? Great, why don't you send me a <a href="https://help.github.com/articles/using-pull-requests">Pull
Request (PR)</a> so everyone can benefit from it? To help you getting started, <a href="https://github.com/SQiShER/java-object-diff/blob/master/CONTRIBUTING.md">here</a> is a brief guide with everyting you need to know to get involved!</p>
<h2>
<a name="donate" class="anchor" href="#donate"><span class="octicon octicon-link"></span></a>Donate</h2>
<p>If you’d like to support this project with a small donation, you can do so via <a href="https://flattr.com/submit/auto?user_id=SQiShER&url=https://github.com/SQiShER/java-object-diff&title=java-object-diff&language=&tags=github&category=software">Flattr</a> or <a href="https://blockchain.info/address/19kRmHJ4qMnYCY6rnY6kCf96Prj6WGxisk">Bitcoin</a>.</p>
<p>Alternatively you could send me a <a href="https://twitter.com/SQiShER">nice tweet</a>, start contributing, write a blog post about this project, tell your friends about it or simply star <a href="https://github.com/SQiShER/java-object-diff">this repository</a>. I'm happy about everything that shows me that someone out there is actually using this library and appreciates all the hard work that goes into its development.</p>
<p><a href="https://flattr.com/submit/auto?user_id=SQiShER&url=https://github.com/SQiShER/java-object-diff&title=java-object-diff&language=&tags=github&category=software"><img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this git repo"></a></p>
</section>
<aside id="sidebar">
<a href="https://github.com/SQiShER/java-object-diff/zipball/master" class="button">
<small>Download</small>
.zip file
</a>
<a href="https://github.com/SQiShER/java-object-diff/tarball/master" class="button">
<small>Download</small>
.tar.gz file
</a>
<p class="repo-owner"><a href="https://github.com/SQiShER/java-object-diff"></a> is maintained by <a href="https://github.com/SQiShER">SQiShER</a>.</p>
<p>This page was generated by <a href="https://pages.github.com">GitHub Pages</a> using the Architect theme by <a href="https://twitter.com/jasonlong">Jason Long</a>.</p>
</aside>
</div>
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-170506-5");
pageTracker._trackPageview();
} catch(err) {}
</script>
</body>
</html>