Lightning APIs for Grails V 0.5.2-Beta, 2019-02-07
Introduction
Grails 3.3.x Plugin to integrate LightningJ into a Grails application.
For more information on LightningJ project see https://www.lightningj.org
More information and source code can be found on the Github site. There it is possible to report issues and contribute code.
If you want updates on this project, follow https://twitter.com/LightningJ_org on twitter.
Important: This API is still in beta and API methods might change before real production release.
All use of this library is on your own risk.
License
This library is Open Source and released under the LGPL v3 License. A link to the license agreement can be found here.
Whats New
-
0.5.2-Beta : Updated with 0.5.2-Beta version of LightningJ
-
0.5.0-Beta : Updated with 0.5.0-Beta version of LightningJ
-
0.5.0-Beta-rc2 : Updated with 0.5.0-Beta-rc2 version of LightningJ
-
0.5.0-Beta-rc1 : Updated with 0.5.0-Beta-rc1 version of LightningJ
-
0.4.2-Beta-2 : Updated with 0.4.2-Beta-2 version of LightningJ
-
0.4.2-Beta : Updated with 0.4.2 version of LightningJ
-
0.4.1-Beta : Updated with 0.4.1 version of LightningJ
-
0.3-Beta : This is the initial release with LndService and Controller enhancements.
Roadmap
-
Create example application showing how to integrate lightning calls inside your web application.
-
Support asynchronous feedback to browser.
Using LightningJ-Grails Library
Step 1 Add Plugin to build.gradle
In the dependencies section add:
compile "org.lightningj:lightningj-grails:0.5.2-Beta"
All tags and releases is signed with bintrays internal GPG keys due to lack of support of SmartCard Signing in the grails plugin publishing process.
Step 2 Add LND Configuration
In application.yml add configuration to initialize the LND Service APIs
# LightingJ Grails configuration lightningj: lnd: host: localhost port: 20001 trustedcert: "~/Library/Application Support/Lnd/tls.cert" macaroon: "~/Library/Application Support/Lnd/admin.macaroon"
The host, port and trustedcert settings are mandatory and macaroon might be omitted if LND is run in --nomacaroons mode.
If more advanced configuration is needed it is possible to initialize LND APIs using a custom GRPC ManagedChannel, but this have to be done before any LND API calls. For instance in BootStrap.groovy. To manually initialize the APIs call the lndService.init(..) method and in that case is no settings in application.yml required.
Step 3 Inject the LND Service
In your artifacts (controller, services, etc) will LndService be injected automatically. See example below on how to access the different APIs.
class InvoiceController {
LndService lndService
def index() {
// To make a synchronous call use lndService.sync.<method>
lndService.sync.walletBalance()
// To make a asynchronous call use lndService.async.<method>
lndService.async.walletBalance(new StreamObserver<WalletBalanceResponse>() {
@Override
void onNext(WalletBalanceResponse value) {
}
@Override
void onError(Throwable t) {
}
@Override
void onCompleted() {
}
})
// To access the wallet APIs use lndService.wallet.sync.<method> and lndService.wallet.async.<method>
}
Important remember to add some form of authorization mechanism since the code above will make calls to LND anonymous.
For more details on how to use the APIs see https://www.lightningj.org and the library’s JavaDoc
Controller Enhancements
The plugin enhances all controllers with two help methods to simplify the conversion between JSON and or XML and wrapped LND GRPC Messages.
The first method are 'asMessage(Class messageType)' that automatically parses request data into LND message depending on the content negotiation done by the client, i.e the contentType sent in the request.
The second method is a render(Message message) method that renders the wrapped LND message into content negotiated format (XML or JSON). Either by the client specifying the content type in the 'Accept' header or by ending the controller url with '.json' or '.xml'.
Supported contentTypes in request and responses are 'application/json', 'text/json', 'application/xml' and 'text/xml'.
Here is an example of a controller using the extra methods:
class InvoiceController {
LndService lndService
def index() {
// asMessage converts from XML or JSON to wrapped LND Message
Invoice invoice = asMessage Invoice
// Call LND using the sync API
AddInvoiceResponse response = lndService.sync.addInvoice(invoice)
// Render the response back to JSON or XML
render response
}
}
Building the Plugin
To build from source clone the repository and use gradlew to build.
git clone https://github.com/lightningj-org/lightningj-grails.git cd lightningj-grails ./gradlew install
The generated plugin can now be used in your project by using mavenLocal.