Joda-Convert 2.2.3 · org.joda.convert.RenameHandler

A general purpose utility for registering renames.

This handles type and enum constant renames. For example, use as follows:

 RenameHandler.INSTANCE.renamedType("org.joda.OldName", NewName.class);
 RenameHandler.INSTANCE.renamedEnum("CORRECT", Status.VALID);
 RenameHandler.INSTANCE.renamedEnum("INCORRECT", Status.INVALID);

From v2.1, renames can be stored on the classpath in configuration files. The file location is META-INF/org/joda/convert/Renamed.ini. All files found in this location are read and processed. The format has two sections [types] and [enums]. The [types] section has lines of the format oldClassName = newClassName. The [enums] section has lines of the format oldEnumConstantName = enumClassName.newEnumConstantName. Lines starting with # are treated as comments.

The recommended usage is to edit the static singleton before using other classes. Editing a static is acceptable because renames are driven by bytecode which is static. For additional security, an application should lock the rename handler instance once any types and enums have been registered using lock().

This class is thread-safe with concurrent caches.

Field Summary

Modifier and Type	Field and Description
private final ConcurrentHashMap<Class<?>, Map<String, Enum<?>>>	enumRenames The enum renames.
public static final RenameHandler	INSTANCE A mutable global instance.
private volatile boolean	locked The lock flag.
private static final boolean	LOG Errors in class initialization are hard to debug.
private final ConcurrentHashMap<String, Class<?>>	typeRenames The type renames.

Constructor Summary

Access	Constructor and Description
private	RenameHandler() Restricted constructor.

Method Summary

Modifier and Type	Method and Description
private void	checkNotLocked()
public static RenameHandler	Returns: a new instance, not null create() Creates an instance.
public static RenameHandler	Returns: a new instance, not null create(boolean whether to load any types in classpath config files loadFromClasspath) Creates an instance, providing the ability to load types in config files.
private static RenameHandler	createInstance()
public Map<String, Enum<?>>	Returns: a copy of the set of enum renames, not null getEnumRenames(Class<?> the enum type, not null type) Gets the map of renamed for an enum type.
public Set<Class<?>>	Returns: a copy of the set of enum types with renames, not null getEnumTypesWithRenames() Gets the set of enum types that have renames.
public Map<String, Class<?>>	Returns: a copy of the set of enum types with renames, not null getTypeRenames() Gets the map of renamed types.
private void	loadFromClasspath()
private List<String>	loadRenameFile(URL url)
public void	lock() Locks this instance of the rename handler.
public < the type of the desired enum T extends Enum<T>> T	Returns: the enum value, not null lookupEnum(Class<T> the enum type, not null type, String the name of the enum to lookup, not null name) Lookup an enum from a name, handling renames.
public Class<?>	Returns: the type, not null lookupType(String the name of the type to lookup, not null name) Lookup a type from a name, handling renames.
private void	parseRenameFile(List<String> lines, URL url)
public void	renamedEnum(String the old name of the enum constant, not null oldName, Enum<?> the current enum constant, not null currentValue) Register the fact that an enum constant was renamed.
public void	renamedType(String the old name of the type including the package name, not null oldName, Class<?> the current type, not null currentValue) Register the fact that a type was renamed.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

enumRenames	back to summary
private final ConcurrentHashMap<Class<?>, Map<String, Enum<?>>> enumRenames The enum renames.

INSTANCE	back to summary
public static final RenameHandler INSTANCE A mutable global instance. This is a singleton instance which is mutated. It will be populated by the contents of the `Renamed.ini` configuration files.

locked	back to summary
private volatile boolean locked The lock flag.

LOG	back to summary
private static final boolean LOG Errors in class initialization are hard to debug. Set -Dorg.joda.convert.debug=true on the command line to add extra logging to System.err Note This also forces `StringConvert` to be loaded before calling `createInstance()` which is vital to avoid horrid ordering issues when loading Renamed.ini classes that reference `StringConvert`.

typeRenames	back to summary
private final ConcurrentHashMap<String, Class<?>> typeRenames The type renames.

Constructor Detail

RenameHandler	back to summary
private RenameHandler() Restricted constructor.

Method Detail

checkNotLocked	back to summary
private void checkNotLocked()

create	back to summary
public static RenameHandler create() Creates an instance. This is not normally used as the preferred option is to edit the singleton. Returns:RenameHandler a new instance, not null

create

back to summary

public static RenameHandler create()

Creates an instance.

This is not normally used as the preferred option is to edit the singleton.

Returns:RenameHandler: a new instance, not null

create	back to summary
public static RenameHandler create(boolean loadFromClasspath) Creates an instance, providing the ability to load types in config files. This is not normally used as the preferred option is to edit the singleton. If the flag is set to true, the classpath config files will be used to register types and enums. Parameters loadFromClasspath:boolean whether to load any types in classpath config files Returns:RenameHandler a new instance, not null

create

back to summary

public static RenameHandler create(boolean loadFromClasspath)

Creates an instance, providing the ability to load types in config files.

This is not normally used as the preferred option is to edit the singleton.

If the flag is set to true, the classpath config files will be used to register types and enums.

Parameters

loadFromClasspath:boolean: whether to load any types in classpath config files

Returns:RenameHandler

a new instance, not null

createInstance	back to summary
private static RenameHandler createInstance()

getEnumRenames	back to summary
public Map<String, Enum<?>> getEnumRenames(Class<?> type) Gets the map of renamed for an enum type. An empty map is returned if there are no renames. Parameters type:Class<?> the enum type, not null Returns:Map<String, Enum<?>> a copy of the set of enum renames, not null

getEnumRenames

back to summary

public Map<String, Enum<?>> getEnumRenames(Class<?> type)

Gets the map of renamed for an enum type.

An empty map is returned if there are no renames.

Parameters

type:Class<?>: the enum type, not null

Returns:Map<String, Enum<?>>

a copy of the set of enum renames, not null

getEnumTypesWithRenames	back to summary
public Set<Class<?>> getEnumTypesWithRenames() Gets the set of enum types that have renames. An empty set is returned if there are no renames. Returns:Set<Class<?>> a copy of the set of enum types with renames, not null

getEnumTypesWithRenames

back to summary

public Set<Class<?>> getEnumTypesWithRenames()

Gets the set of enum types that have renames.

An empty set is returned if there are no renames.

Returns:Set<Class<?>>: a copy of the set of enum types with renames, not null

getTypeRenames	back to summary
public Map<String, Class<?>> getTypeRenames() Gets the map of renamed types. An empty map is returned if there are no renames. Returns:Map<String, Class<?>> a copy of the set of enum types with renames, not null

getTypeRenames

back to summary

public Map<String, Class<?>> getTypeRenames()

Gets the map of renamed types.

An empty map is returned if there are no renames.

Returns:Map<String, Class<?>>: a copy of the set of enum types with renames, not null

loadFromClasspath	back to summary
private void loadFromClasspath()

loadRenameFile	back to summary
private List<String> loadRenameFile(URL url) throws IOException

lock	back to summary
public void lock() Locks this instance of the rename handler. For additional security, an application should lock the rename handler once any types and enums have been registered.

lock

back to summary

public void lock()

Locks this instance of the rename handler.

For additional security, an application should lock the rename handler once any types and enums have been registered.

lookupEnum	back to summary
public <T extends Enum<T>> T lookupEnum(Class<T> type, String name) Lookup an enum from a name, handling renames. Parameters <T> the type of the desired enum type:Class<T> the enum type, not null name:String the name of the enum to lookup, not null Returns:T the enum value, not null Exceptions IllegalArgumentException: if the name is not a valid enum constant

lookupEnum

back to summary

public <T extends Enum<T>> T lookupEnum(Class<T> type, String name)

Lookup an enum from a name, handling renames.

Parameters

<T>: the type of the desired enum
type:Class<T>: the enum type, not null
name:String: the name of the enum to lookup, not null

Returns:T

the enum value, not null

Exceptions

IllegalArgumentException:: if the name is not a valid enum constant

lookupType	back to summary
public Class<?> lookupType(String name) throws ClassNotFoundException Lookup a type from a name, handling renames. Parameters name:String the name of the type to lookup, not null Returns:Class<?> the type, not null Exceptions ClassNotFoundException: if the name is not a valid type

lookupType

back to summary

public Class<?> lookupType(String name) throws ClassNotFoundException

Lookup a type from a name, handling renames.

Parameters

name:String: the name of the type to lookup, not null

Returns:Class<?>

the type, not null

Exceptions

ClassNotFoundException:: if the name is not a valid type

parseRenameFile	back to summary
private void parseRenameFile(List<String> lines, URL url)

renamedEnum	back to summary
public void renamedEnum(String oldName, Enum<?> currentValue) Register the fact that an enum constant was renamed. This handles the use case where an enum constant is renamed, but the enum class remains the same. Parameters oldName:String the old name of the enum constant, not null currentValue:Enum<?> the current enum constant, not null

renamedEnum

back to summary

public void renamedEnum(String oldName, Enum<?> currentValue)

This handles the use case where an enum constant is renamed, but the enum class remains the same.

Parameters

oldName:String: the old name of the enum constant, not null
currentValue:Enum<?>: the current enum constant, not null

renamedType	back to summary
public void renamedType(String oldName, Class<?> currentValue) Register the fact that a type was renamed. This handles the use case where a class is renamed. Parameters oldName:String the old name of the type including the package name, not null currentValue:Class<?> the current type, not null

renamedType

back to summary

public void renamedType(String oldName, Class<?> currentValue)

This handles the use case where a class is renamed.

Parameters

oldName:String: the old name of the type including the package name, not null
currentValue:Class<?>: the current type, not null

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Returns:String a string representation of the object. Annotations @Override

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations

@Override

public final Class RenameHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail