org.lightningj.paywall.paymenthandler

Class BasePaymentHandler

java.lang.Object

org.lightningj.paywall.paymenthandler.BasePaymentHandler

All Implemented Interfaces:

LightningEventListener, PaymentHandler

Direct Known Subclasses:

SpringPaymentHandler

public abstract class BasePaymentHandler
extends java.lang.Object
implements PaymentHandler, LightningEventListener

Abstract Base PaymentHandler containing common logic to simplify implementation of specific implementation and let them focus on persisting payment data and looking up information for a given order from an order request.

Created by Philip Vendil on 2018-12-09.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.util.logging.Logger	log
protected PaymentDataConverter	paymentDataConverter
protected PaymentEventBus	paymentEventBus

Constructor Summary

Constructors

Constructor and Description
BasePaymentHandler() Empty Constructor

Method Summary

Modifier and Type	Method and Description
Settlement	checkSettlement(byte[] preImageHash, boolean includeInvoice) Method to check if a given preImageHash is settled and returns a settlement value object if invoice is settled.
Order	createOrder(byte[] preImageHash, OrderRequest orderRequest) Method to create an order from a preImageHash and and order request.
protected abstract PaymentData	findPaymentData(byte[] preImageHash) Method to lookup a payment data in the payment handler.
protected abstract java.time.Duration	getDefaultInvoiceValidity()
protected abstract java.time.Duration	getDefaultSettlementValidity()
protected abstract LightningHandler	getLightningHandler() Method that should returned the used LightningHandler.
LightningHandlerContext	getLightningHandlerContext() Method to generate the latest LNDLightningHandlerContext of latest known state of the lightning node.
void	init() Method that is called during the startup the application to set up all required sub components of the PaymentHandler.
protected abstract boolean	isLightningHandlerAutoconnect()
Invoice	lookupInvoice(byte[] preImageHash) Method to lookup an invoice in the PaymentHandler.
void	markAsExecuted(byte[] preImageHash) Method to flag a related payment flow is a pay per request type and has been processed successfully.
protected abstract PaymentData	newPaymentData(byte[] preImageHash, OrderRequest orderRequest) Method that should generate a new PaymentData for a given order request.
void	onLightningEvent(LightningEvent event) This method is called every time an lightning invoice was added or settled.
void	registerListener(PaymentListener listener) Method to add the listener to the set of listeners listening on payment events.
Settlement	registerSettledInvoice(Invoice settledInvoice, boolean registerNew, OrderRequest orderRequest, LightningHandlerContext context) Method to manually register an invoice as settled (isSettled must be set to true) used in some payment flows instead of listening on lightningHandler events.
void	unregisterListener(PaymentListener listener) Method to remove the listener to the set of listeners listening on payment events.
protected abstract void	updatePaymentData(PaymentEventType type, PaymentData paymentData, LightningHandlerContext context) Method called on update events about a given payment data.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static java.util.logging.Logger log

paymentEventBus

protected PaymentEventBus paymentEventBus

paymentDataConverter

protected PaymentDataConverter paymentDataConverter

Constructor Detail

BasePaymentHandler

public BasePaymentHandler()

Empty Constructor

Method Detail

init

public void init()
          throws InternalErrorException

Method that is called during the startup the application to set up all required sub components of the PaymentHandler.

Specified by:

init in interface PaymentHandler

Throws:

InternalErrorException - if internal error occurred setting up the PaymentHandler.

createOrder

public Order createOrder(byte[] preImageHash,
                         OrderRequest orderRequest)
                  throws java.io.IOException,
                         InternalErrorException

Method to create an order from a preImageHash and and order request. The implementation should lookup the article id and return an order with all required fields set.

Specified by:

createOrder in interface PaymentHandler

Parameters:

preImageHash - the unique preImageHash used to identify a payment flow withing a lightning payment.

orderRequest - the specification of the order that should be created calculated from data in the PaymentRequired annotation.

Returns:

a newly created order used to create a lightning invoice in LightningHandler.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred creating the order.

lookupInvoice

public Invoice lookupInvoice(byte[] preImageHash)
                      throws java.io.IOException,
                             InternalErrorException

Method to lookup an invoice in the PaymentHandler. The payment handler might call the LightningHandler to get complementary data about the invoice.

Specified by:

lookupInvoice in interface PaymentHandler

Parameters:

preImageHash - the unique preImageHash used to identify an invoice withing a lightning payment.

Returns:

the related invoice or null if no invoice with related preImageHash found.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred looking up the invoice.

checkSettlement

public Settlement checkSettlement(byte[] preImageHash,
                                  boolean includeInvoice)
                           throws AlreadyExecutedException,
                                  java.lang.IllegalArgumentException,
                                  java.io.IOException,
                                  InternalErrorException

Method to check if a given preImageHash is settled and returns a settlement value object if invoice is settled.

Specified by:

checkSettlement in interface PaymentHandler

Parameters:

preImageHash - the preImageHash of the invoice to check.

includeInvoice - if a invoice should be included in the settlement response. This might consume more resources.

Returns:

a settlement value object of related preImageHash if invoice is settled, otherwise null.

Throws:

AlreadyExecutedException - if related payment is pay per request and is already executed.

java.lang.IllegalArgumentException - if related payment is per request and is already executed.

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred looking up the settlement.

registerSettledInvoice

public Settlement registerSettledInvoice(Invoice settledInvoice,
                                         boolean registerNew,
                                         OrderRequest orderRequest,
                                         LightningHandlerContext context)
                                  throws java.lang.IllegalArgumentException,
                                         java.io.IOException,
                                         InternalErrorException

Method to manually register an invoice as settled (isSettled must be set to true) used in some payment flows instead of listening on lightningHandler events.

Specified by:

registerSettledInvoice in interface PaymentHandler

Parameters:

settledInvoice - a settled invoice that should be registered in the payment handler.

registerNew - if a new payment data should be created if no prior object existed for related preImageHash.

orderRequest - the specification of the order that should be created calculated from data in the PaymentRequired annotation. Only used if new payment data needs to be registered.

context - the latest known state of the lightning handler. Null if no known state exists.

Returns:

a settlement value object for the given settledInvoice.

Throws:

java.lang.IllegalArgumentException - if settled invoices preImageHash does exists as payment data and registerNew is false or related invoice isn't settled.

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred registering a settled invoice.

markAsExecuted

public void markAsExecuted(byte[] preImageHash)
                    throws java.io.IOException,
                           InternalErrorException

Method to flag a related payment flow is a pay per request type and has been processed successfully.

Specified by:

markAsExecuted in interface PaymentHandler

Parameters:

preImageHash - the preImageHash of the payment to mark as processed.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred updating the payment or no related payment found.

registerListener

public void registerListener(PaymentListener listener)
                      throws InternalErrorException

Method to add the listener to the set of listeners listening on payment events.

Specified by:

registerListener in interface PaymentHandler

Parameters:

listener - the listener to register.

Throws:

InternalErrorException - if internal exception occurred registering the listener.

unregisterListener

public void unregisterListener(PaymentListener listener)
                        throws InternalErrorException

Method to remove the listener to the set of listeners listening on payment events.

Specified by:

unregisterListener in interface PaymentHandler

Parameters:

listener - the listener to un-register.

Throws:

InternalErrorException - if internal exception occurred un-registering the listener.

getLightningHandlerContext

public LightningHandlerContext getLightningHandlerContext()
                                                   throws InternalErrorException

Method to generate the latest LNDLightningHandlerContext of latest known state of the lightning node. Used to make sure the PaymentHandler starts listening on the correct location of the invoice event queue after restart. The BasePaymentHandler just returns empty context for simplicity. This isn't recommended for an production setup since settled invoices in lightning node might be missed during restart. Lightning context is updated through when lightning events are triggered.

Specified by:

getLightningHandlerContext in interface PaymentHandler

Returns:

the last known state of lightning handler context.

Throws:

InternalErrorException - if internal exception occurred fetching latest known state of lightning handler.

getLightningHandler

protected abstract LightningHandler getLightningHandler()

Method that should returned the used LightningHandler.

Returns:

the related LightningHandler.

getDefaultInvoiceValidity

protected abstract java.time.Duration getDefaultInvoiceValidity()

Returns:

the default validity for generated invoices if no expire date have been set explicit in PaymentData.

getDefaultSettlementValidity

protected abstract java.time.Duration getDefaultSettlementValidity()

Returns:

the default validity for generated settlements if no valid until date have been set explicit in PaymentData.

isLightningHandlerAutoconnect

protected abstract boolean isLightningHandlerAutoconnect()
                                                  throws InternalErrorException

Returns:

true if base payment handler should try to connect to lightning handler automatically upon restart.

Throws:

InternalErrorException - if problems occurred parsing configuration.

newPaymentData

protected abstract PaymentData newPaymentData(byte[] preImageHash,
                                              OrderRequest orderRequest)
                                       throws java.io.IOException,
                                              InternalErrorException

Method that should generate a new PaymentData for a given order request. This is the first call in a payment flow and the implementation should look up the order amount from the article id, units and other options in the order request. The generated PaymentData should be at least MinimalPaymentData with preImageHash and orderedAmount set. It is recommended that the PaymentData is persisted in this call but could be skipped for performance in certain payment flows.

Parameters:

preImageHash - the unique preImageHash used to identify a payment flow withing a lightning payment.

orderRequest - the specification of the payment data that should be created calculated from data in the PaymentRequired annotation.

Returns:

a newly generated PaymentData signaling a new payment flow used to create an Order value object.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred generating new payment data.

findPaymentData

protected abstract PaymentData findPaymentData(byte[] preImageHash)
                                        throws java.io.IOException,
                                               InternalErrorException

Method to lookup a payment data in the payment handler.

Parameters:

preImageHash - the unique preImageHash used to identify a payment flow withing a lightning payment.

Returns:

return related payment data or null if not found.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred fetching related payment data.

updatePaymentData

protected abstract void updatePaymentData(PaymentEventType type,
                                          PaymentData paymentData,
                                          LightningHandlerContext context)
                                   throws java.io.IOException,
                                          InternalErrorException

Method called on update events about a given payment data. This could be when the payment is added as invoice in LND and contains complementary data or when the invoice was settled and contains settled flag set and settled amount and date (depending on the type of PaymentData used in PaymentHandler). The related payment data (using preImageHash as unique identifier) is automatically looked up and the implementing method should at least persist the updated data.

Parameters:

type - the type of event such as INVOICE_CREATED or INVOICE_SETTLED.

paymentData - the payment data to update and persist.

context - the latest known state of the lightning handler. Null if no known state exists.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred updating related payment data.

onLightningEvent

public void onLightningEvent(LightningEvent event)

This method is called every time an lightning invoice was added or settled.

Specified by:

onLightningEvent in interface LightningEventListener

Parameters:

event - the related lightning event.

See Also:

LightningEvent