Example: Floating License Server

Step 1: declare licensing requirements

FLS architects defined three features for this product, meaning these three functions are designed to be matched with licensing coverage:

org.eclipse.passage.lbc.fls.product - feature of the product as a whole and thus must be identified with the product id;
org.eclipse.passage.lbc.acquire.concurrent - base, limited edition of one particular internal function;
org.eclipse.passage.lbc.acquire.concurrent.full - unlimited edition of the same functionality.

It was also agreed (usually defined by marketing department), that the first two features is allowed to be used in an absence of a license, but with warnings that remind user of insufficient license coverage.

The last feature can be used only when licensed properly.

After evolution, all three features achieve some mature state which was coined as 2.0.0 version.

Thus, developer declares licensing requirements for these three features.

Licensing requirements for the core product feature org.eclipse.passage.lbc.fls.product is declared in FLS Seal plug-in as it represents the product on the bundles level:

Provide-Capability: licensing.feature;licensing.feature="org.eclipse.passage.lbc.fls.product";name="Eclipse Passage Floating License Server";version="2.0.0";provider="Eclispe Passage";level="warn"

The requirement is declared with warn restriction level, which precisely means if there is no license, expose warning to a user. This work is to be done by the development as well.

Development guarantees, that the core feature identifier is precisely equal to the product identifier, which is our case can be found in FLS product declaration.

Licensing requirements for the base feature org.eclipse.passage.lbc.acquire.concurrent is declared in LBC Base bundle: there is no API exposed by LBC component, thus licensing requirement for a feature must reside close to its implementation as a part of the feature contract.

Location of the requirements described here is recommended as a part of approved methodology, but not required. Passage Access Cycle will find your licensing requirement in any runtime available bundle.

Licensing requirements for the premium feature org.eclipse.passage.lbc.acquire.concurrent.full declared next to its basic version.

But unlike it, this one is exposed under error restriction level as it's not supposed to be used if not licensed.

Step 2: employ Passage Access Cycle

Access Cycle is the part of Passage that runs together with your product and empowers licensing protection at your product runtime.

Three things should be done in you product's code base to utilize Access Cycle:

add dependency to org.eclipse.passage.lic.execute.feature,
configure Access Cycle,
get a product public key from the management (which generated it with Passage Operator when next product version is defined and signed for release) and include it in this version product distribution.

As FLS is itself for Passage and on Passage product, it gains the vital dependency with the rest of Passage parts necessary for functioning.

Access Cycle configuration and product public key reside in a dedicated bundle, methodologically called seal.

To configure Access Cycle a developer must supply instance of Passage Framework interface by means of the current infrastructure DI. For Eclipse ecosystem we use OSGi implementation.

Have a look at FlsFramework:

it provides an instance of AccessCycleConfiguration, packed with all necessary services, to Passage runtime
and its Supplier is declared as OSGi Component to be injected into DI container and thus accessible at Passage runtime.

The public key file is placed in OSGI-INF folder of the same bundle, which supplies Framework instance to the Passage runtime. The file is included in the bundle binary build.

Step 3: implant license checks

A product developer appeals to Access Cycle by means of Passage Lic API to cover each of the features implementation with licensing protection.

FLS checks license coverage when each of the features, declared to licensing protection, is going to be executed.

The first feature, org.eclipse.passage.lbc.fls.product, as it denotes the product core feature, is checked for license coverage each time the server starts up.

Have a closer loot at LicenseProtection class that implements the check.

It has two pairing methods:
check, which gets a licensing grant for the feature and report failed check if none is granted, and
release, which returns the grant, it it has indeed been acquired.

Correspondingly,
check is called by start server command and
release is triggered on server stop.

The basic org.eclipse.passage.lbc.acquire.concurrent feature is checked when the corresponding functionality is invoked: when FLS a client tries to acquire a grant for a product feature under FLS responsibility.

And the premium org.eclipse.passage.lbc.acquire.concurrent.full feature is checked when the basic functionality is not enough.

Look how ProtectedGrantCapacity, which checks if the premium grant acquisition is properly licensed, is exploited by AcquiredGrantsStorage, which, in turn, is responsible for the grant acquisition in general.