diff --git a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy index 2348552051..42dc8ff41a 100644 --- a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy +++ b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy @@ -2,27 +2,54 @@ package com.r3corda.plugins import org.gradle.api.DefaultTask import org.gradle.api.tasks.TaskAction - import java.nio.file.Path import java.nio.file.Paths +/** + * Creates nodes based on the configuration of this task in the gradle configuration DSL. + * + * See documentation for examples. + */ class Cordform extends DefaultTask { protected Path directory = Paths.get("./build/nodes") protected List nodes = new ArrayList() protected String networkMapNodeName - public String directory(String directory) { + /** + * Set the directory to install nodes into. + * + * @param directory The directory the nodes will be installed into. + * @return + */ + public void directory(String directory) { this.directory = Paths.get(directory) } - public String networkMap(String nodeName) { + /** + * Set the network map node. + * + * @warning Ensure the node name is one of the configured nodes. + * @param nodeName The name of one the node that will host the network map. + */ + public void networkMap(String nodeName) { networkMapNodeName = nodeName } + /** + * Add a node configuration. + * + * @param configureClosure A node configuration that will be deployed. + */ public void node(Closure configureClosure) { nodes << project.configure(new Node(project), configureClosure) } + /** + * Returns a node by name. + * + * @param name The name of the node as specified in the node configuration DSL. + * @return A node instance. + */ protected Node getNodeByName(String name) { for(Node node : nodes) { if(node.name.equals(networkMapNodeName)) { @@ -33,6 +60,9 @@ class Cordform extends DefaultTask { return null } + /** + * Installs the run script into the nodes directory. + */ protected void installRunScript() { project.copy { from Cordformation.getPluginFile(project, "com/r3corda/plugins/runnodes") @@ -42,8 +72,11 @@ class Cordform extends DefaultTask { } } + /** + * This task action will create and install the nodes based on the node configurations added. + */ @TaskAction - def build() { + void build() { installRunScript() Node networkMapNode = getNodeByName(networkMapNodeName) nodes.each { diff --git a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy index 4e17f4836b..61f6b4bed6 100644 --- a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy +++ b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy @@ -2,14 +2,20 @@ package com.r3corda.plugins import org.gradle.api.Plugin import org.gradle.api.Project -import org.gradle.api.resources.TextResource +/** + * The Cordformation plugin deploys nodes to a directory in a state ready to be used by a developer for experimentation, + * testing, and debugging. It will prepopulate several fields in the configuration and create a simple node runner. + */ class Cordformation implements Plugin { - void apply(Project project) { - - } - - static def getPluginFile(Project project, String filePathInJar) { + /** + * Gets a resource file from this plugin's JAR file. + * + * @param project The project environment this plugin executes in. + * @param filePathInJar The file in the JAR, relative to root, you wish to access. + * @return A file handle to the file in the JAR. + */ + static File getPluginFile(Project project, String filePathInJar) { return project.resources.text.fromArchiveEntry(project.buildscript.configurations.classpath.find { it.name.contains('cordformation') }, filePathInJar).asFile() diff --git a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy index fa81453e38..2e3f0b82d3 100644 --- a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy +++ b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy @@ -1,11 +1,16 @@ package com.r3corda.plugins -import org.gradle.api.file.FileCollection import org.gradle.api.internal.file.AbstractFileCollection +/** + * Represents a node that will be installed. + */ class Node { static final String JAR_NAME = 'corda.jar' + /** + * Name of the node. + */ public String name private String dirName private String nearestCity @@ -20,50 +25,108 @@ class Node { private File nodeDir private def project + /** + * Set the name of the node. + * + * @param name The node name. + */ void name(String name) { this.name = name } + /** + * Set the directory the node will be installed to relative to the directory specified in Cordform task. + * + * @param dirName Subdirectory name for node to be installed to. Must be valid directory name on all OSes. + */ void dirName(String dirName) { this.dirName = dirName } + /** + * Set the nearest city to the node. + * + * @param nearestCity The name of the nearest city to the node. + */ void nearestCity(String nearestCity) { this.nearestCity = nearestCity } + /** + * Sets whether this node will be a notary + * + * @param isNotary True if this node is a notary. + */ void notary(Boolean isNotary) { this.isNotary = isNotary } + /** + * Sets whether this node will use HTTPS communication. + * + * @param isHttps True if this node uses HTTPS communication. + */ void https(Boolean isHttps) { this.isHttps = isHttps } + /** + * Set the advertised services for this node. + * + * @param advertisedServices A list of advertised services ID strings. + */ void advertisedServices(List advertisedServices) { this.advertisedServices = advertisedServices } + /** + * Set the artemis port for this node. + * + * @param artemisPort The artemis messaging queue port. + */ void artemisPort(Integer artemisPort) { this.artemisPort = artemisPort } + /** + * Set the HTTP web server port for this node. + * + * @param webPort The web port number for this node. + */ void webPort(Integer webPort) { this.webPort = webPort } + /** + * Set the network map address for this node. + * + * @warning This should not be directly set unless you know what you are doing. Use the networkMapName in the + * Cordform task instead. + * @param networkMapAddress Network map address. + */ void networkMapAddress(String networkMapAddress) { this.networkMapAddress = networkMapAddress } + /** + * Set the list of cordapps to use on this node. + * + * @note Your app will be installed by default and does not need to be included here. + * @param cordapps The list of cordapps to install to the plugins directory. + */ void cordapps(List cordapps) { this.cordapps = cordapps } - Node(def project) { + Node(Project project) { this.project = project } + /** + * Install the nodes to the given base directory. + * + * @param baseDir The base directory for this node. All other paths are relative to it + this nodes dir name. + */ void build(File baseDir) { nodeDir = new File(baseDir, dirName) installCordaJAR() @@ -73,10 +136,18 @@ class Node { installConfig() } + /** + * Get the artemis address for this node. + * + * @return This node's artemis address. + */ String getArtemisAddress() { return "localhost:" + artemisPort } + /** + * Installs the corda fat JAR to the node directory. + */ private void installCordaJAR() { def cordaJar = verifyAndGetCordaJar() project.copy { @@ -86,6 +157,9 @@ class Node { } } + /** + * Installs this project's cordapp to this directory. + */ private void installBuiltPlugin() { def pluginsDir = getAndCreateDirectory(nodeDir, "plugins") project.copy { @@ -94,6 +168,9 @@ class Node { } } + /** + * Installs other cordapps to this node's plugins directory. + */ private void installCordapps() { def pluginsDir = getAndCreateDirectory(nodeDir, "plugins") def cordapps = getCordappList() @@ -103,6 +180,9 @@ class Node { } } + /** + * Installs other dependencies to this node's dependencies directory. + */ private void installDependencies() { def cordaJar = verifyAndGetCordaJar() def cordappList = getCordappList() @@ -114,6 +194,9 @@ class Node { } } + /** + * Installs the configuration file to this node's directory and detokenises it. + */ private void installConfig() { project.copy { from Cordformation.getPluginFile(project, 'com/r3corda/plugins/nodetemplate.conf') @@ -133,6 +216,11 @@ class Node { } } + /** + * Find the corda JAR amongst the dependencies. + * + * @return A file representing the Corda JAR. + */ private File verifyAndGetCordaJar() { def maybeCordaJAR = project.configurations.runtime.filter { it.toString().contains("corda-${project.corda_version}.jar")} if(maybeCordaJAR.size() == 0) { @@ -144,6 +232,11 @@ class Node { } } + /** + * Gets a list of cordapps based on what dependent cordapps were specified. + * + * @return List of this node's cordapps. + */ private AbstractFileCollection getCordappList() { def cordaJar = verifyAndGetCordaJar() return project.configurations.runtime.filter { @@ -152,6 +245,13 @@ class Node { } } + /** + * Create a directory if it doesn't exist and return the file representation of it. + * + * @param baseDir The base directory to create the directory at. + * @param subDirName A valid name of the subdirectory to get and create if not exists. + * @return A file representing the subdirectory. + */ private static File getAndCreateDirectory(File baseDir, String subDirName) { File dir = new File(baseDir, subDirName) assert(!dir.exists() || dir.isDirectory())