Package com.github.crashdemons.playerheads.compatibility

Class Compatibility

  • public final class Compatibility
extends Object
    Compatibility class controlling implementation and version support.

    This class forms the basis of most plugin access to the compatibility package methods through chaining.

    Note: some methods of this class may not be thread-safe. Generally you should only change provider registrations on the main thread during plugin load or enable, then only afterwards use isProviderAvailable / getProvider methods freely.

    Author:
    crashdemons (crashenator at gmail.com)

    • Method Detail

      • init

        public static boolean init()
                    throws UnknownVersionException,
                           CompatibilityUnsupportedException,
                           CompatibilityUnavailableException,
                           CompatibilityConflictException
        Initialize compatibility support.

        This method initializes server version-detection and selects compatibility providers (specific Bukkit implementations) for use later. This method also makes a determination as to what the recommended implementation version is.

        The "recommended" version is the highest implementation version available (for your server's type) that is under or equal to your server version. If no provider with a matching type can be found, this method will look for one with the 'fallback' server type (which at this time defaults to "craftbukkit").

        Provider implementations are expected to exist in the same package as the compatibility library (com.github.crashdemons.playerheads.compatibility by default). followed by the server type name and major/minor version. For example: com.github.crashdemons.playerheads.compatibility.craftbukkit_1_16 the class in this package must be named "Provider" and must not be abstract.

        Returns:
        Whether the recommended implementation version was used. True: the best implementation version for your server that was supported was loaded. False: a fallback implementation was used - possibly because you loaded a backport implementation onto a newer server improperly.
        Throws:
        UnknownVersionException - If the server version string could not be understood during detection.
        CompatibilityUnsupportedException - If the server version was lower than is supported by the compatibility package (minimum 1.8)
        CompatibilityUnavailableException - If no implementation could be found that is compatible with your server. This may happen if all available providers (of a compatible type) are newer than your server version, or no matches can be found for your server type or fallback type.
        CompatibilityConflictException - If an implementation provider was already registered - this happens when there is more than one call to init and registerProvider.
        CompatibilityMisconfiguredException - If the compatibility library was not properly built (with supported versions finalized).

      • isProviderAvailable

        public static boolean isProviderAvailable()
        Determine if a compatibility implementation has been registered yet.
        Returns:
        whether a provider is available yet

      • registerProvider

        public static void registerProvider​(CompatibilityProvider obj)
                             throws CompatibilityConflictException
        Registers an compatibility provider (a bukkit-version-specific implementation) for the session with the compatibility class.

        You should either use this or init(), but not both and not more than once - providers cannot be unregistered at this time.

        Parameters:
        obj - The implementation to register
        Throws:
        CompatibilityConflictException - If an implementation is already registered when you called this function.
        See Also:
        CompatibilityProvider, init()

      • unregisterProvider

        @Deprecated
public static boolean unregisterProvider()
        Deprecated.
        registering an unregistering multiple providers is not recommended since it means loading unnecessary classes into memory and changing the state of compatibility.
        Unregisters the currently registered Compatibility Provider for the session.
        Returns:
        whether there was a provider to unregister (same result as isProviderAvailable())

      • getRecommendedProviderType

        public static String getRecommendedProviderType()
        Gets the current recommended implementation type name for your server based on the supported implementations.

        If you call this before init(), it will always return an empty string.

        Returns:
        the implementation type name, or an empty string if it is not yet available.

      • getRecommendedProviderVersion

        public static String getRecommendedProviderVersion()
        Gets the current recommended bukkit-specific implementation version string for your server based on the supported implementations.

        If you call this before init(), it will always return an empty string.

        Returns:
        The version string, or an empty string if it is not yet available.