net.openhft.chronicle.core.pool

Class StringInterner

java.lang.Object

net.openhft.chronicle.core.pool.StringInterner

public class StringInterner
extends Object

StringInterner only guarantees it will behave in a correct manner. When you ask it for a String for a given input, it must return a String which matches the toString() of that CharSequence.

It doesn't guarantee that all threads see the same data, nor that multiple threads will return the same String object for the same string. It is designed to be a best-effort basis so it can be as lightweight as possible.

So while technically not thread safe, it doesn't prevent it operating correctly when used from multiple threads, but it is faster than added explicit locking or thread safety. NOTE: It does rely on String being thread safe, something which was guaranteed from Java 5.0 onwards c.f. JSR 133.

Discussion ...

This class provides string interning functionality. It's used to optimize memory usage by caching strings and referring to them by index, rather than storing duplicate strings. When you 'intern' a string, it's looked up in the cache and if an equal string is found, it's returned instead of creating a new one.

Author:

peter.lawrey

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	StringInterner.Changed

Field Summary

Fields

Modifier and Type	Field and Description
protected String[]	interner
protected int	mask
protected int	shift
protected boolean	toggle

Constructor Summary

Constructors

Constructor and Description
StringInterner(int capacity) Constructs a new StringInterner with the specified capacity.

Method Summary

Modifier and Type	Method and Description
int	capacity()
String	get(int index) get an intered string based on the index
int	index(@Nullable CharSequence cs, @Nullable StringInterner.Changed onChanged) provide
@Nullable String	intern(@Nullable CharSequence cs) Interns the specified CharSequence.
protected boolean	toggle()
int	valueCount() Returns the number of values in the interner.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

interner

protected final String[] interner

mask

protected final int mask

shift

protected final int shift

toggle

protected boolean toggle

Constructor Detail

StringInterner

public StringInterner(int capacity)
               throws IllegalArgumentException

Constructs a new StringInterner with the specified capacity.

Parameters:

capacity - the initial capacity of the interner.

Throws:

IllegalArgumentException - if the capacity is invalid.

Method Detail

capacity

public int capacity()

Returns:

the size of interner[]

intern

@Nullable
public @Nullable String intern(@Nullable
                                         @Nullable CharSequence cs)

Interns the specified CharSequence.

Parameters:

cs - the CharSequence to intern.

Returns:

the interned string, or the original CharSequence if it's not interned.

index

public int index(@Nullable
                 @Nullable CharSequence cs,
                 @Nullable
                 @Nullable StringInterner.Changed onChanged)

provide

Parameters:

cs - a source string

Returns:

the index that the internered string is stored in, or -1 if not stored

An example of the StringInterner used in conjunction with the uppercase[] to cache another value

 private String[] uppercase;

 public void myMethod() throws IllegalArgumentException {

         StringInterner si = new StringInterner(128);
         uppercase = new String[si.capacity()];

         String lowerCaseString = ...

         int index = si.index(lowerCaseString, this::changed);
         if (index != -1)
             assertEquals(lowerCaseString.toUpperCase(), uppercase[index]);
 }

 private void changed(int index, String value) {
      uppercase[index] = value.toUpperCase();
 }

 

get

public String get(int index)

get an intered string based on the index

Parameters:

index - the index of the interner string, to acquire an index call index(java.lang.CharSequence, net.openhft.chronicle.core.pool.StringInterner.Changed)

Returns:

interned String

toggle

protected boolean toggle()

valueCount

public int valueCount()

Returns the number of values in the interner.

Returns:

the count of non-null strings in the interner.