corda/docs/source/corda-plugins.rst
Shams Asari 329e5ff17b Introducing InitiatedBy annotation to be used on initiated flows to simplify flow registration.
This removes the need to do manual registration using the PluginServiceHub. As a result CordaPluginRegistry.servicePlugins is no longer needed. For oracles and services there is a CorDappService annotation.

I've also fixed the InitiatingFlow annotation such that client flows can be customised (sub-typed) without it breaking the flow sessions.
2017-05-31 10:50:16 +01:00

2.6 KiB

The Corda plugin framework

The intention is that Corda is a common platform, which will be extended by numerous application extensions (CorDapps). These extensions will package together all of the Corda contract code, state structures, protocols/flows to create and modify state as well as RPC extensions for node clients. Details of writing these CorDapps is given elsewhere creating-a-cordapp.

To enable these plugins to register dynamically with the Corda framework the node uses the Java ServiceLoader to locate and load the plugin components during the AbstractNode.start call. Therefore, to be recognised as a plugin the component must:

1. Include a default constructable class extending from net.corda.core.node.CordaPluginRegistry which overrides the relevant registration methods.

2. Include a resource file named net.corda.core.node.CordaPluginRegistry in the META-INF.services path. This must include a line containing the fully qualified name of the CordaPluginRegistry implementation class. Multiple plugin registries are allowed in this file if desired.

3. The plugin component must be on the classpath. In the normal use this means that it should be present within the plugins subfolder of the node's workspace.

4. As a plugin the registered components are then allowed access to some of the node internal subsystems.

5. The overridden properties on the registry class information about the different extensions to be created, or registered at startup. In particular:

a. The webApis property is a list of JAX-RS annotated REST access classes. These classes will be constructed by the bundled web server and must have a single argument constructor taking a CordaRPCOps reference. This will allow it to communicate with the node process via the RPC interface. These web APIs will not be available if the bundled web server is not started.

b. The staticServeDirs property maps static web content to virtual paths and allows simple web demos to be distributed within the CorDapp jars. These static serving directories will not be available if the bundled web server is not started.

c. The customizeSerialization function allows classes to be whitelisted for object serialisation, over and above those tagged with the @CordaSerializable annotation. In general the annotation should be preferred. For instance new state types will need to be explicitly registered. This will be called at various points on various threads and needs to be stable and thread safe. See serialization.