Shariff Java Backend

Shariff is used to determine how often a page is shared in social media, but without generating requests from the displaying page to the social sites.

This document describes the Java backend. It is some kind of a port of the offical Shariff PHP backend.

This Shariff backend is not a part of the official backends by Heise Online!

Features

• Easy to use Java servlet
• Supports addthis, facebook, flattr, linkedin, pinterest, reddit, stumbleupon, vk, xing
• Parallel counter fetching to minimize response time
• Comes with a simple caching mechanism that can be replaced by other cache solutions like Ehcache
• Built with maven, package is available at Maven Central
• Uses slf4j, for log output just add a binding to your classpath
• Requires Java 8 or higher (Java 7 up to version 1.1)

Installing the Shariff backend on your own server

Just add Shariff (org.shredzone.shariff:backend:1.4) to your maven or gradle dependencies, or copy the shariff.jar, json.jar and slf4j files to your project's lib folder. Then add the Shariff servlet to your web.xml:

<servlet>
    <servlet-name>shariff</servlet-name>
    <servlet-class>org.shredzone.shariff.ShariffServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>shariff</servlet-name>
    <url-pattern>/shariff/</url-pattern>
</servlet-mapping>

Use init-param to configure the servlet:

<servlet>
    <servlet-name>shariff</servlet-name>
    <servlet-class>org.shredzone.shariff.ShariffServlet</servlet-class>
    <init-param>
        <param-name>targets</param-name>
        <param-value>flattr,facebook</param-value>
    </init-param>
</servlet>

The following configuration options are available:

Key	Description
host	Regular expression of acceptable hosts (e.g. "^(.*\.)?example\.com$"). If unset, only the host of the servlet is accepted. It's recommended to keep foreign websites from using your Shariff server.
cache.size	Maximum number of urls to be cached in memory. Default is 1000.
cache.timeToLiveMs	Maximum time urls are cached, in ms. Default is 1 minute.
cache.useOnError	If true, a cached counter is reused if the current counter could not be fetched (e.g. because of a rate limit). This way, the cache time to live could be considerably exceeded for individual counters. Default is false.
targets	List of services to be enabled (see Features). Case sensitive. Services must be separated by comma. Default is all available services.
threads	Number of fetcher threads. Defaults to number of active targets.
facebook.id	The app ID of your Facebook application.
facebook.secret	The app secret of your Facebook application.
organisation	When set, your organisation will appear in the user agent of any request which is made by the shariff backend

Note that you must set up facebook.id and facebook.secret to retrieve a valid Facebook share counter. Facebook does not offer an anonymous way any more, at least none I am aware of.

The configuration keys cacheSize and cacheTimeToLiveMs are deprecated since v1.7, but are still accepted.

Testing your installation

If the backend runs under http://example.com/shariff/, calling the URL http://example.com/shariff/?url=http%3A%2F%2Fwww.example.com should return a JSON structure with numbers in it, e.g.:

{"facebook":1452,"flattr":23}

You can also invoke ShariffBackend directly. Pass in the Facebook credentials via system properties facebook.id and facebook.secret if necessary. It returns the share counters for the given URLs on the command line:

java -cp backend.jar:json.jar:slf4j-api.jar:slf4j-simple.jar \
  -Dfacebook.id=myAppId -Dfacebook.secret=myAppSecret \
  org.shredzone.shariff.ShariffBackend \
  http://www.heise.de

Shariff Servlet

You can extend the ShariffServlet class and override its protected methods if you need more control about fetching or caching the count data.

To replace the caching mechanism (e.g. by Ehcache), override the getCountsCached() method.

For reading and normalizing the url parameter, override the getUrl() method.

For an individual test whether the given url contains a valid host or not, override the isValidHost() method.

Use this snippet to set the Facebook credentials programmatically:

Facebook facebook = getBackend().getTarget(Facebook.class);
if (facebook != null) {
    facebook.setSecret(yourClientId, yourClientSecret);
}

License

shariff-backend-java is released under the terms of the Apache License 2.0.