Module org.joda.convert
Package org.joda.convert

Class RenameHandler

java.lang.Object
org.joda.convert.RenameHandler
public final class RenameHandler extends Object
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.

Since:
1.6

  • Field Details

    • INSTANCE

      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.

  • Method Details

    • create

      public static RenameHandler create()
      Creates an instance.

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

      Returns:
      a new instance, not null

    • create

      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 - whether to load any types in classpath config files
      Returns:
      a new instance, not null

    • renamedType

      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 - the old name of the type including the package name, not null
      currentValue - the current type, not null

    • getTypeRenames

      public Map<String,Class<?>> getTypeRenames()
      Gets the map of renamed types.

      An empty map is returned if there are no renames.

      Returns:
      a copy of the set of enum types with renames, not null

    • lookupType

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

    • renamedEnum

      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 - the old name of the enum constant, not null
      currentValue - the current enum constant, not null

    • getEnumTypesWithRenames

      public Set<Class<?>> getEnumTypesWithRenames()
      Gets the set of enum types that have renames.

      An empty set is returned if there are no renames.

      Returns:
      a copy of the set of enum types with renames, not null

    • getEnumRenames

      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 - the enum type, not null
      Returns:
      a copy of the set of enum renames, not null

    • lookupEnum

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

    • lock

      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.

    • toString

      public String toString()
      Overrides:
      toString in class Object