greenrobot-common
greenrobot
1277
Visit GitHub RepoUtils

Essentials

Build Status

Essentials are a collection of general-purpose classes we found useful in many occasions.

  • Write less code in your projects
  • Specialized implementations for better performance compared to standard APIs
  • Super light weight: < 100k in size
  • Compatible with Android and Java

This project is bare bones compared to a rich menu offered by Guava or Apache Commons. Essentials is not a framework, it's rather a small set of utilities to make Java standard approaches more convenient or more efficient.

Website

JavaDoc (3.0 release candidate)

Changelog

Features

  • IO utilities help with streams (byte and character based) and digests (e.g. MD5 and SHA-1).
  • File utilities simplify reading and writing strings/bytes/objects from or to files. Also includes getting hashes from files and copying files.
  • String utilities allow efficient splitting and joining of strings, hex and MD5 creation, and other useful string helpers.
  • Date utilities.
  • Better hash functions: our Murmur3 implementation provides superior hash quality and outperforms standard Java hash functions
  • Specialized Streams: for example an optimized PipedOutputStream replacement (based on a circular byte buffer)
  • Hash set and map for primitive long keys outperform the generic versions of the Java Collection APIs
  • Multimaps provide a map of lists or sets to simplify storing multiple values for a single key
  • Object cache with powerful configuration options: soft/weak/strong references, maximum size, and time-based expiration
  • Base64 implementation (bundled from iharder.net) for lower versions of Java & Android (includes input/output streams)

Read more on our website.

Add the dependency to your project

You may also try the 3.0 release candidate with additional features and a cleaned up API:

compile 'org.greenrobot:essentials:3.0.0-RC1'

Or, grab the older version:

compile 'de.greenrobot:java-common:2.3.1'

And for Maven:

<dependency>
    <groupId>de.greenrobot</groupId>
    <artifactId>java-common</artifactId>
    <version>2.3.1</version>
</dependency>

Code samples (V2.3.1)

Example code on how to use some of the utility classes:

// Get all bytes from stream and close the stream safely
byte[] bytes = IoUtils.readAllBytesAndClose(inputStream);

// Read the contents of an file as a string (use readBytes to get byte[])
String contents = FileUtils.readUtf8(file);

// How many days until new year's eve?
long time2 = DateUtils.getTimeForDay(2015, 12, 31);
int daysToNewYear = DateUtils.getDayDifference(time, time2);

Multimaps (added in V2.2):

ListMap<String,String> multimap = new ListMap<>();
multimap.putElement("a", "1");
multimap.putElement("a", "2");
multimap.putElement("a", "3");
List<String> strings = multimap.get("a"); // Contains "1", "2", and "3"

Our hash functions implement java.util.zip.Checksum, so this code might look familiar to you:

Murmur3A murmur = new Murmur3A();
murmur.update(bytes);
long hash = murmur.getValue();

All hashes can be calculated progressively by calling update(...) multiple times. Our Murmur3A implementation goes a step further by offering updates with primitive data in a very efficient way:

// reuse the previous instance and start over to calculate a new hash
murmur.reset();

murmur.updateLong(42L);

// Varargs and arrays are supported natively, too  
murmur.updateInt(2014, 2015, 2016);

murmur.updateUtf8("And strings, of course");

// Hash for the previous update calls. No conversion to byte[] necessary.
hash = murmur.getValue();

The utility classes are straight forward and don't have dependencies, so you should be fine to grasp them by having a look at their source code. Most of the method names should be self-explaining, and often you'll find JavaDocs where needed.

Build setup

Currently, Maven is used to build greenrobot-common. Inside of build-common, there are two parent POMs defined that might be useful: parent-pom and parent-pom-with-checks. The latter integrates FindBugs and Checkstyle in your build. Use it like this:

<parent>
    <groupId>de.greenrobot</groupId>
    <artifactId>parent-pom-with-checks</artifactId>
    <version>2.0.0</version>
    <relativePath></relativePath>
</parent>

License

Copyright (C) 2012-2016 Markus Junginger, greenrobot (http://greenrobot.org)

EventBus binaries and source code can be used according to the Apache License, Version 2.0.

More Open Source by greenrobot

EventBus is a central publish/subscribe bus for Android with optional delivery threads, priorities, and sticky events. A great tool to decouple components (e.g. Activities, Fragments, logic components) from each other.

greenDAO is an ORM optimized for Android: it maps database tables to Java objects and uses code generation for optimal speed.

Follow us on Google+ to stay up to date.

Become a better Android Developer
Millions of developers are learning at MindOrks

Online Training Program

Featured Blogs

Our Team

MindOrks is Certainly one of the best online blog to stay on top of all the Android development news, coding and design patterns. Finally a blog I can count on to keep myself updated with latest and greatest things happening in Android world.

Vipul Shah
Android Developer
Microsoft

Become Pro in Android by watching videos

OUR LEARNERS WORK AT