public final class Compatibility
-extends java.lang.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.
registering an unregistering multiple providers is not recommended since it means loading unnecessary classes into memory and changing the state of compatibility.
- 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.
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.
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())
An interface specifying all of the methods we need for our plugin that require differing Bukkit-specific implementations which we wish to abstract from our plugin code.
- CompatibilityProviders not only must implement this interface, but in order to be automatically selected by the Compatibility class,
- they must exist in a specific package name.
-
- Providers (or a class extending them) 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.
-
- Secondly, to be automatically selected by the Compatibility class, the server type and version must be listed in the CompatibilitySupport class' VERSIONS map.
- This is typically accomplished by replacing it in the compatibility-library module when shading in all relevant support classes (ie: the original is excluded from shading).
This method does not include extended checking, you probably dont want the direct method.
-
-
Gets the owning player of a skull as direct as possible from the relevant API - this may not always reliably get the player.
-
- This method may not result in the same information as getOwner, you should check both.
-
-
Parameters:
-
skullItemMeta - the ItemMeta of the skull
-
Returns:
-
the player owning the skull, or null if none could be retrieved.
This method does not include extended checking, you probably dont want the direct method.
-
-
Gets the owning player of a skull as direct as possible from the relevant API - this may not always reliably get the player.
-
- This method may not result in the same information as getOwner, you should check both.
-
-
Parameters:
-
skullBlockState - the BlockState of the skull
-
Returns:
-
the player owning the skull, or null if none could be retrieved.
Gets the owning player of a skull, with an additional attempt to derive the player from Profile uuid.
-
- This method may not result in the same information as getOwner, you should check both.
- This method does not exhaustively attempt to derive players from usernames.
-
-
Parameters:
-
skullItemMeta - the ItemMeta of the skull
-
Returns:
-
the player owning the skull, or null if none could be retrieved.
Gets the owning player of a skull, with an additional attempt to derive the player from Profile uuid.
-
- This method may not result in the same information as getOwner, you should check both.
- This method does not exhaustively attempt to derive players from usernames.
-
-
Parameters:
-
skullBlockState - the BlockState of the skull
-
Returns:
-
the player owning the skull, or null if none could be retrieved.
This method does not include extended checking, you probably dont want the direct method.
-
-
Gets the owner username of a skull as direct as possible from the relevant API - this may not always reliably get the username.
-
- This method may not result in the same information as getOwningPlayerDirect, you should check both.
This method does not include extended checking, you probably dont want the direct method.
-
-
Gets the owner username of a skull as direct as possible from the relevant API - this may not always reliably get the username.
-
- This method may not result in the same information as getOwningPlayerDirect, you should check both.
Gets the owner username of a skull by any means necessary.
-
- Because of differing results between getOwningPlayer().getName() and getOwnerDirect(), it may be necessary to use both or check the profile field, which this method should do.
- This method must be implemented with the following defined order: getOwningPlayer and getProfilePlayer if necessary to check name, then getOwner to check name.
-
-
Parameters:
-
skullItemMeta - the itemmeta of the skull to check
Gets the owner username of a skull by any means necessary.
-
- Because of differing results between getOwningPlayer().getName() and getOwnerDirect(), it may be necessary to use both or check the profile field, which this method should do.
- This method must be implemented with the following defined order: getOwningPlayer and getProfilePlayer if necessary to check name, then getOwner to check name.
-
-
Parameters:
-
skullBlockState - the blockstate of the skull to check
Gets the vanilla skulltype best associated with the ItemStack provided.
-
- Note: this method does not perform any username, UUID, or texture checks, so any skull that is not directly supported in the current server (such as a dragon head in 1.8) will return SkullType.PLAYER instead.
- It only determines what skulltype is associated with the vanilla types available.
Gets the vanilla skulltype best associated with the BlockState provided.
-
- Note: this method does not perform any username, UUID, or texture checks, so any skull that is not directly supported in the current server (such as a dragon head in 1.8) will return SkullType.PLAYER instead.
- It only determines what skulltype is associated with the vanilla types available.
Gets a forward-portable name of an entity.
-
- This gets the name of the entity as it appears in the EntityType enum of newer bukkit versions, even if the mob is a variant in the current version.
- This value can be used to correspond entities to their heads.
This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
-
-
Gets the Profile object associated with a head, if possible.
- The return type is offered as an Object to remove reliance on authlib.
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
- Providers that are not capable of retrieving this should throw an IllegalStateException.
-
-
Parameters:
-
headMeta - the meta of the head item
-
Returns:
-
the Profile object object for the head, or null.
-
Throws:
-
java.lang.IllegalStateException - when the provider does not support GameProfiile access.
This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
-
-
Gets the Profile object associated with a head, if possible.
- The return type is offered as an Object to remove reliance on authlib.
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
-
-
Parameters:
-
headBlockState - the blockstate of the head block
-
Returns:
-
the Profile object object for the head, or null.
-
Throws:
-
java.lang.IllegalStateException - when the provider does not support GameProfiile access.
This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
-
-
Sets the Profile object on a head, if possible.
- Providers that are not capable of retrieving this should throw an IllegalStateException.
- IllegalArgumentException should be thrown if the input is not null and also not a Profile object type.
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
-
-
Parameters:
-
headMeta - the meta of the head item
-
profile - the Profile object object to set in the head
-
Returns:
-
whether setting the profile field succeeded
-
Throws:
-
java.lang.IllegalStateException - when the provider does not support GameProfiile access.
-
java.lang.IllegalArgumentException - when the the input profile was not am acceptable Profile object type and not null
This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
-
-
Sets the Profile object on a head, if possible.
- Providers that are not capable of retrieving this should throw an IllegalStateException.
- IllegalArgumentException should be thrown if the input is not null and also not a Profile object type.
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
-
-
Parameters:
-
headBlockState - the blockstate of the head block
-
profile - the Profile object object to set in the head
-
Returns:
-
whether setting the profile field succeeded
-
Throws:
-
java.lang.IllegalStateException - when the provider does not support GameProfiile access.
-
java.lang.IllegalArgumentException - when the the input profile was not am acceptable Profile object type and not null
Gets the Optional Profile object for a head.
- This method must return an Optional object which 'is present' if the profile has a retrievable value (including null).
- Otherwise, the Optional must be 'empty'.
Gets the Optional Profile object for a head.
- This method must return an Optional object which 'is present' if the profile has a retrievable value (including null).
- Otherwise, the Optional must be 'empty'.
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile or even present - you should not act on this object directly, but only get/set it.
Sets the Optional Profile object for a head.
- If the Optional value is 'empty' (not present), then nothing happens.
- If the Optional value is present, then it is set (even if it is null).
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile or even present - you should not act on this object directly, but only get/set it.
-
-
Parameters:
-
skullState - the blockstate for a head item
-
profile - the Optional profile object to set
-
Returns:
-
whether setting the profile succeeded. (nothing happening is considered failure).
Sets the Optional Profile object for a head.
- If the Optional value is 'empty' (not present), then nothing happens.
- If the Optional value is present, then it is set (even if it is null).
- NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile or even present - you should not act on this object directly, but only get/set it.
-
-
Parameters:
-
skullMeta - the meta for a head item
-
profile - the Optional profile object to set
-
Returns:
-
whether setting the profile succeeded. (nothing happening is considered failure).
Create a compatible profile object with the provided parameters.
- Note: name and id cannot both be null, only one can be null.
-
-
Parameters:
-
name - the owner username of the head (this should not be a custom name - use null instead)
-
id - A UUID to be associated with this profile and texture (this may be a custom/unique value that you manage - you are strongly recommended to choose a static but randomly-generated ID)
-
texture - The Base64-encoded Texture-URL tags. (this may be null to set no texture)
-
Returns:
-
the CompatibleProfile object
-
Throws:
-
java.lang.IllegalArgumentException - if both the name and id are null.
Gets the head used as a base for a displaying a given vanilla skull type.
- Note: if the particular skull-type is not supported in your server version, this will create a Player-type head
- for you to use for skinning/placeholding.
- If you want more control over head happens in these cases, consider using CompatibleSkullMaterial directly.
-
-
Parameters:
-
material - the supported compatible skull material/type
public final class CompatibilitySupport
-extends java.lang.Object
-
Class that holds supported compatibility implementations in this release.
- By default, before shading, this is mostly empty and it is up to the
- downstream projects to add support.
- Downstream projects that shade the package into their project should exclude
- or replace this class as needed.
public static finaljava.util.HashMap<java.lang.String,java.lang.Integer[][]>VERSIONS
-
Map containing the supported server implementations and their supported
- versions.
- This list must be in order of descending version numbers for each type.
- Types do not have to be in any specific order.
- For example: VERSIONS.put("craftbukkit", new Integer[][]{ {1,16},{1,13},{1,8} });
-
-
-
-
-
-
-
-
-
Method Details
-
-
-
-
isFinalized
-
public staticbooleanisFinalized()
-
Specifies whether compatibility support has been added by a downstream
- project yet.
- If this is false, the project was not created properly.
public final class CompatiblePlugins
-extends java.lang.Object
-
Class providing methods and information for inter-plugin compatibility.
-
- This class may attempt to load some present configuration values.
- You can avoid this using your plugin's config directly by using the
- init(plugin,config) method.
Generic head support class that determines handling of detected plugin-heads (eg: being able to ignore them)
-
-
-
-
-
-
-
-
-
Method Details
-
-
-
-
init
-
public staticvoidinit(Plugin parentPluginInstance)
-
Initialize plugin support classes.
- This should be done during plugin Enable or afterwards - you may need to
- add a SoftDepend entry for the plugin to be detected in onEnable.
-
- Note: it's recommended to call this *after* Compatibility.init so that
- supported plugin classes have access to other compatibility methods.
-
- If this method is used, the top level parent plugin config section is
- used for plugin-support config entries.
-
-
Parameters:
-
parentPluginInstance - the plugin requesting compatibility support
Initialize plugin support classes.
- This should be done during plugin Enable or afterwards - you may need to
- add a SoftDepend entry for the plugin to be detected in onEnable.
-
- Note: it's recommended to call this *after* Compatibility.init so that
- supported plugin classes have access to other compatibility methods.
-
-
Parameters:
-
parentPluginInstance - the plugin requesting compatibility support
-
config - the configuration section to use for plugin-support entries
-
-
-
-
-
-
reloadConfig
-
public staticvoidreloadConfig()
-
-
-
-
-
testBlockBreak
-
public staticbooleantestBlockBreak(Block block,
-Player player)
-
Test of a simulated block break succeeds (considering all applicable
- plugin support classes).
- This method includes exempting fastbreak in NCP before testing.
-
-
Parameters:
-
block - the block being broken
-
player - the player doing the breaking
-
Returns:
-
whether the block break succeeded or failed (was cancelled).
-
-
-
-
-
-
isReady
-
public staticbooleanisReady()
-
Checks whether the plugin compatibility classes are ready for use.
- (whether the class init completed without exception)
public abstract class CompatibleProfile
-extends java.lang.Object
-
Utility class that may be used by compatibility providers to handle head profile information.
- A profile is defined as a username,id, and optional properties such as a texture.
- Using this class is currently optional except where required in CompatibilityProvider
- Implementations should treat a null or empty value for any field as not existing/not present.
Constructs a profile object from some implementation-defined representation of profiles.
- This method should be overridden to prevent exceptions
-
-
Parameters:
-
internalProfile - the implementation-defined representation of a profile.
-
-
-
-
-
-
-
-
-
-
Method Details
-
-
-
-
hasField
-
public staticbooleanhasField(java.util.UUID obj)
-
-
-
-
-
hasField
-
public staticbooleanhasField(java.lang.String obj)
-
-
-
-
-
hasRequiredFields
-
public staticbooleanhasRequiredFields(java.util.UUID id,
-java.lang.String name)
-
-
-
-
-
setFromInternalObject
-
public abstractvoidsetFromInternalObject(java.lang.Object internalProfile)
- throws java.lang.IllegalArgumentException
-
Sets fields/values of the profile object from an implementation-defined representation of profiles.
- This method is overridden by each implementation.
- If no internal implementation is available, providers should take CompatibleProfile itself instead of an exception.
- An IllegalArgumentException may be thrown if the object type is incorrect.
java.lang.IllegalArgumentException - when the parameter was not an internal type used by the current provider.
-
-
-
-
-
-
toInternalObject
-
public abstractjava.lang.ObjecttoInternalObject()
-
Gets an implementation-defined representation for the profile information.
- If no internal implementation is available, providers should return CompatibleProfile itself instead of null/exception
Gets the OfflinePlayer associated with the profile.
- Uses the same logic order that bukkit does: returns the ID-based Player if a player exists, OR the name-based player if a username exists, but only one will be checked.
An enumeration of vanilla skull/head materials (items and blocks) that can
- possibly be supported.
-
- This abstracts both new materials and old materials+datavalues (skull
- variants) into matching categories by enum along with their
- implementation-specific details.
-
- Entries from newer versions may appear here, but are backed by playerhead
- materials if they are not supported - which can be checked with
- isSupported().
- Generally this corresponds with an entry for each entry in SkullType
Returns the enum constant of this type with the specified name.
-The string must match exactly an identifier used to declare an
-enum constant in this type. (Extraneous whitespace characters are
-not permitted.)
-
-
Parameters:
-
name - the name of the enum constant to be returned.
-
Returns:
-
the enum constant with the specified name
-
Throws:
-
java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
-
java.lang.NullPointerException - if the argument is null
Defines an interface of implementation-specific details and methods relating
- to a skull item/block.
-
- Generally, a set of Skull implementation details is available for each
- vanilla skull type.
-
- Depending on implemnentation, some of the block and item materials returned
- by methods here may be the same or different.
public enum SkullType
-extends java.lang.Enum<SkullType>
-
An enumeration of skulls and heads that are supported in vanilla servers.
-
- This enum corresponds in ordinal value to entries of the deprecated Bukkit
- SkullType enum,
- however the names here instead generally correspond to the vanilla item name
- (Material).
-
- This enum adds information to entries about whether each type is a proper
- skull or a head - which is relevant to specific implementation materials and
- naming.
Returns an array containing the constants of this enum type, in
-the order they are declared.
-
-
Returns:
-
an array containing the constants of this enum type, in the order they are declared
-
-
-
-
-
-
valueOf
-
public staticSkullTypevalueOf(java.lang.String name)
-
Returns the enum constant of this type with the specified name.
-The string must match exactly an identifier used to declare an
-enum constant in this type. (Extraneous whitespace characters are
-not permitted.)
-
-
Parameters:
-
name - the name of the enum constant to be returned.
-
Returns:
-
the enum constant with the specified name
-
Throws:
-
java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
-
java.lang.NullPointerException - if the argument is null
Exception indicating that there is a conflict between multiple
- compatibility-provider implementations.
- This generally occurs when attempting to register a second provider for the
- session or initialize the compatibility library twice, mistakenly.
Exception indicating that the Compatibility library project was misconfigured
- when it was built, not correctly finalizing support information.
-
- This generally means that support providers (CompatibilityProvider
- implementations) were not indicated to have been added.
Exception indicating that an implementation providing compatibility for the
- current server couldn't be found or is otherwise unavailable.
-
- This occurs when either Compatibility initialization has exhausted all
- options or the current method cannot load the specified provider.
-
- The second case may occur if version support was indicated to exist, but was
- not shaded in - this was common in legacy backports that only supported
- specifics versions, but modern builds usually have 1:1 representation in
- CompatibilitySupport.
Exception indicating that a compatibility-provider implementation isn't
- registered at a time when it is required.
-
- This occurs if you sttempt to use an implementation-specific compatibility
- method such as getProvider() without a provider/implementation having been
- made available by Compatibility.init() or registerProvider()
Exception indicating a server version that is incompatible with the available
- implementations.
-
- Unlike "Unavailable" exception, this is used for cases where support will not
- be provided or even checked. By default this includes any server versions
- below 1.8.
Package supplying cross-version compiling compatibility to the plugin.
-
- This functions by providing a common interface of required methods, with
- differing implementations based on bukkit version.
An interface specifying all of the methods we need for our plugin that require differing Bukkit-specific implementations which we wish to abstract from our plugin code.
An interface specifying all of the methods we need for our plugin that require differing Bukkit-specific implementations which we wish to abstract from our plugin code.
An interface specifying all of the methods we need for our plugin that require differing Bukkit-specific implementations which we wish to abstract from our plugin code.
Get the plugin instance for the third-party plugin being supported.
- This method has Bukkit look-up the plugin name every time it is called,
- unless the plugin name is blank - you should use get() instead.
-
-
Returns:
-
the plugin instance, or null of the plugin name is blank
-
-
-
-
-
-
isReady
-
publicbooleanisReady()
-
Whether the plugin compatibility class is ready to be used.
- (By default this is true unless overridden)
-
-
Returns:
-
whether the class is ready.
-
-
-
-
-
-
isPresent
-
publicbooleanisPresent()
-
Whether the supported third-party plugin was detected to be present on
- the server.
-
-
Returns:
-
whether the plugin is present.
-
-
-
-
-
-
getName
-
publicjava.lang.StringgetName()
-
Gets the proper name of the third-party plugin this class attempts to
- support.
Get the plugin instance for the third-party plugin being supported.
- This method only looks up the plugin name with Bukkit if it was initially
- detected to be present.
-
-
Returns:
-
the plugin instance, or null if the plugin was not present at
- startup.
Event used internally by the plugin to detect if a hypothetical BlockBreak
- would be cancelled by another plugin.
-
- Used in determining whether drops should occur when heads might be broken by
- a player. This is useful when using plugins such as WorldGuard that cancel
- blockbreak in protected areas.
-
- This version of the class currently extends FakeBlockBreakEvent so that
- external plugin compatibility is not broken, but this is intended to be the
- new location of the class in the future.
-
- (Previously FakeBlockBreakEvent)
-
- Note: This documentation was inferred after the fact and may be
- inaccurate.
-
-
Author:
-
meiskam
-
-
-
-
-
-
-
-
Nested Class Summary
-
-
Nested classes/interfaces inherited from class org.bukkit.event.Event
A collection of helper classes providing methods from other bukkit plugins, for use in CompatiblePlugins class to increase compatibility between plugins.
Returns the enum constant of this type with the specified name.
-The string must match exactly an identifier used to declare an
-enum constant in this type. (Extraneous whitespace characters are
-not permitted.)
-
-
Parameters:
-
name - the name of the enum constant to be returned.
-
Returns:
-
the enum constant with the specified name
-
Throws:
-
java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
-
java.lang.NullPointerException - if the argument is null
A collection of helper classes providing methods from other bukkit plugins, for use in CompatiblePlugins class to increase compatibility between plugins.
A collection of helper classes providing methods from other bukkit plugins, for use in CompatiblePlugins class to increase compatibility between plugins.
A collection of helper classes providing methods from other bukkit plugins, for use in CompatiblePlugins class to increase compatibility between plugins.
A collection of helper classes providing methods from other bukkit plugins, for use in CompatiblePlugins class to increase compatibility between plugins.
registering an unregistering multiple providers is not recommended since it means loading unnecessary classes into memory and changing the state of compatibility.
A collection of helper classes providing methods from other bukkit plugins, for use in CompatiblePlugins class to increase compatibility between plugins.
An interface specifying all of the methods we need for our plugin that require differing Bukkit-specific implementations which we wish to abstract from our plugin code.
You should use Compatibility.getProvider() from PlayerHeads-compatibility-api. Compatibility packages will be removed from PH-API in the future, but you may still access them if you use PlayerHeads-compatibility-api (or lib) as a dependency.
registering an unregistering multiple providers is not recommended since it means loading unnecessary classes into memory and changing the state of compatibility.