[[extending]]
== Extending {brandname}
{brandname} can be extended to provide the ability for an end user to add
additional configurations, operations and components outside of the scope of the ones normally provided
by {brandname}.

=== Custom Commands
{brandname} makes use of a link:http://en.wikipedia.org/wiki/Command_pattern[command/visitor pattern] to
implement the various top-level methods you see on the public-facing API.
This is explained in further detail in the link:#arch_overview[Architectural Overview] section.
While the core commands - and their corresponding visitors - are hard-coded as
a part of {brandname}'s core module, module authors can extend and enhance {brandname}
by creating new custom commands.

As a module author (such as link:https://github.com/infinispan/infinispan/tree/master/query[infinispan-query], etc.) you can define your own commands.

You do so by:

. Create a `META-INF/services/org.infinispan.commands.module.ModuleCommandExtensions` file and ensure this is packaged in your jar.
. Implementing link:https://github.com/infinispan/infinispan/blob/master/core/src/main/java/org/infinispan/commands/module/ModuleCommandFactory.java[`ModuleCommandFactory`],
link:https://github.com/infinispan/infinispan/blob/master/core/src/main/java/org/infinispan/commands/module/ModuleCommandInitializer.java[`ModuleCommandInitializer`] and
link:https://github.com/infinispan/infinispan/blob/master/core/src/main/java/org/infinispan/commands/module/ModuleCommandExtensions.java[`ModuleCommandExtensions`]
. Specifying the fully-qualified class name of the  link:https://github.com/infinispan/infinispan/blob/master/core/src/main/java/org/infinispan/commands/module/ModuleCommandExtensions.java[`ModuleCommandExtensions`]
implementation in `META-INF/services/org.infinispan.commands.module.ModuleCommandExtensions`.
. Implement your custom commands and visitors for these commands


==== An Example
Here is an example of an `META-INF/services/org.infinispan.commands.module.ModuleCommandExtensions` file, configured accordingly:

.org.infinispan.commands.module.ModuleCommandExtensions
----
org.infinispan.query.QueryModuleCommandExtensions
----

For a full, working example of a sample module that makes use of custom commands and visitors, check out link:https://github.com/infinispan/infinispan-sample-module[{brandname} Sample Module] .

==== Preassigned Custom Command Id Ranges
This is the list of `Command` identifiers that are used by {brandname} based modules or frameworks.
{brandname} users should avoid using ids within these ranges. (RANGES to be finalised yet!)
Being this a single byte, ranges can't be too large.

|===============
|{brandname} Query:|100 - 119
|Hibernate Search:|120 - 139
|Hot Rod Server:  |140 - 141
|===============

=== Extending the configuration builders and parsers
If your custom module requires configuration, it is possible to enhance {brandname}'s configuration builders and
parsers. Look at the link:https://github.com/infinispan/infinispan/blob/master/core/src/test/java/org/infinispan/configuration/module[custom module tests]
for a detail example on how to implement this.
