ehcache-sizeofengine

What is this?

This library lets you size Java Object instances in bytes.

SizeOf sizeOf = SizeOf.newInstance(); // (1)
long shallowSize = sizeOf.sizeOf(someObject); // (2)
long deepSize = sizeOf.deepSizeOf(someObject); // (3)

Retrieves one of the multiple engines supported;
Sizes someObject instance in bytes;
Sizes someObject instance in bytes, as well as all objects it references.

The different engines

When retrieving a new SizeOf instance with the static org.ehcache.sizeof.SizeOf.newInstance, the library will try to create of the following engines, in that order:

AgentSizeOf : Which tries to attach an agent to the JVM process and size objects using org.ehcache.sizeof.impl.AgentLoader.instrumentation; otherwise
UnsafeSizeOf : Which will determine Class layouts in memory using sun.misc.Unsafe; or finally
ReflectionSizeOf : Which will introspect Class instances and try determining object sizes that way.

Both the ReflectionSizeOf and the AgentSizeOf approach were very well covered in Dr. Heinz Kabutz’s Java Specialist Newsletter issue #78 and issue #142 respectively. Different JVMs and their configurations may affect these sizes, see blob/master/src/main/java/org/ehcache/sizeof/impl/JvmInformation.java[JvmInformation enum] for more details. Finally, the UnsafeSizeOf, we’ve discovered and, as far as we know, were the first ones to use.

Avoiding sizing certain types

In some cases you want to control how far the deep sizing goes. You can do this using the org.ehcache.sizeof.Filter SPI.

Using existing filter configurators

You simply need to add the jars of the modules that you want along side this project’s jar

Configuring the Filter yourself

In order to ignore fields or instances of certain classes when sizing object graphs, you’ll have to

Create a ServiceLoader project, for net.sf.ehcache.sizeofengine.FilterConfigurator
- Have your jar contain a text file named META-INF/services/org.ehcache.sizeof.FilterConfigurator
- The file should contain the fully qualified class name of your implementation
Implement FilterConfigurator's configure method to configure the Filter of classes and fields
put your jar on your application’s classpath, along side of the ehcache jar and this ehcache-sizeofengine jar
Use Ehcache’s Automatic Resource Control for your heap tier

Example

public static final class StupidConfigurator implements FilterConfigurator {

    @Override
    public void configure(final Filter ehcacheFilter) {
        // Will not size any instance of Number, and given the second arg, no subtype neither
        ehcacheFilter.ignoreInstancesOf(Number.class, false);
    }
}

There can be as many FilterConfigurator on the classpath as required, they’ll have configure the filter once. The Filter is shared across all SizeOfEngine instances created.

Using it

Maven

Releases are available from Maven Central.

<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>sizeof</artifactId>
    <version>${sizeof.version}</version>
</dependency>

Snapshots are available from the Sonatype OSS snapshots repository. In order to access the snapshots, you need to add the following repository to your pom.xml:

<repository>
    <id>sonatype-nexus-snapshots</id>
    <name>Sonatype Nexus Snapshots</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
        <enabled>false</enabled>
    </releases>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

guohao/sizeof