diff --git a/prebid-server/developers/add-a-module-java.md b/prebid-server/developers/add-a-module-java.md index 874ec62319..c9f474e84c 100644 --- a/prebid-server/developers/add-a-module-java.md +++ b/prebid-server/developers/add-a-module-java.md @@ -8,7 +8,7 @@ title: Prebid Server | Developers | Adding a Java Module # Prebid Server - Adding a Java Module {: .no_toc} -* TOC +- TOC {:toc } ## Overview @@ -17,7 +17,7 @@ This document details how to make a module for PBS-Java. You will want to be familiar with the following background information: -- the [module overview](/prebid-server/developers/add-a-module.html) +- the [module overview](/prebid-server/developers/add-a-module.html) - the [PBS-Java Modularity Tech Spec](https://docs.google.com/document/d/1VP_pi7L5Iy3ikHMbtC2_rD5RZTVSc3OkTWKvtRS5x5Y/edit#heading=h.oklyk2bogkx4) ### Coding standards @@ -28,7 +28,7 @@ The module’s code style should correspond to the [PBS-Java project code style] The Prebid Server repository contains a maven submodule called `all-modules` located in the `extra/modules` folder. It includes all available PBS modules. So, in order to add a new module, fork the repository and create a folder with the desired name inside the modules folder with the following structure: -``` +```text +- prebid-server-java/ +- extra/ +- modules/ @@ -37,13 +37,13 @@ The Prebid Server repository contains a maven submodule called `all-modules` loc +- pom.xml <- POM of all included modules ``` -A benefit of open sourcing your module in this way is that it can use the parent `all-modules` as a maven dependency. It simplifies management of the PBS-Core and other commonly used dependencies and you will be confident that it works well with the current version of Prebid Server. +A benefit of open sourcing your module in this way is that it can use the parent `all-modules` as a maven dependency. It simplifies management of the PBS-Core and other commonly used dependencies and you will be confident that it works well with the current version of Prebid Server. ### Your module's build file Here's a partial example of your module-specific `pom.xml` file: -``` +```text @@ -60,6 +60,7 @@ Here's a partial example of your module-specific `pom.xml` file: ``` where: + - PREBID_SERVER_VERSION is the current version of Prebid Server. The release team will update this value for all modules with each release, but you need to set it to the version of PBS that you're developing with. - YOUR_MODULE_ARTIFACT_ID is the name of your module JAR file without version and extension. e.g. ortb2-blocking - YOUR_MODULE_TEXTUAL_NAME is unique within the space of all other modules. e.g. instead of naming a module "blocking", a better name would be "ortb2blocking". @@ -68,7 +69,7 @@ where: Add your module within `extra/modules/pom.xml` in the "modules" section: -``` +```text ... YOUR_MODULE_ARTIFACT_ID @@ -79,7 +80,7 @@ Add your module within `extra/modules/pom.xml` in the "modules" section: The structure of your module source code inside the modules directory must have a standard maven-compatible structure: -``` +```text +- src/ +- main/ +- java/ <- source code @@ -95,13 +96,15 @@ The structure of your module source code inside the modules directory must have ## Module Code The quick start is to take a look in two places: + - the [ortb2-blocking module](https://github.com/prebid/prebid-server-java/tree/master/extra/modules/ortb2-blocking) - the [module test cases](https://github.com/prebid/prebid-server-java/tree/master/src/test/java/org/prebid/server/it/hooks) ### Adding module documentation + It is required to add a "README.md" file to the root of your module folder. Recommended this file contains the description of what the implemented module does, links to external documentation and includes maintainer contact info (email, slack, etc). -The documentation must also live on the docs.prebid.org site. Please add a markdown file to https://github.com/prebid/prebid.github.io/tree/master/prebid-server/pbs-modules +The documentation must also live on the docs.prebid.org site. Please add a markdown file to ### Hook Interfaces @@ -124,6 +127,7 @@ These are the available hooks that can be implemented in a module: In a module it is not necessary to implement all mentioned interfaces but only one (or several) required by your functionality. Each hook interface internally extends org.prebid.server.hooks.v1.Hook basic interface with methods should be implemented: + - `code()` - returns module code. - `call(...)` - returns result of hook invocation. @@ -177,7 +181,7 @@ Each hook interface internally extends org.prebid.server.hooks.v1.Hook basic int ); ``` -More test implementations for each hook can be found in unit-tests at https://github.com/prebid/prebid-server-java/tree/master/src/test/java/org/prebid/server/it/hooks folder. +More test implementations for each hook can be found in unit-tests at folder. ### Applying results asynchronously @@ -191,6 +195,16 @@ Thus, for any kind of blocking operations it is recommended to use a Vert.x buil To see how to proceed with async operations, please see similar PBS-Core functionality, for example Currency Conversion Service implementation (class “org.prebid.server.currency.CurrencyConversionService”). +### Available Functions + +#### Getting the localhost CPU + +To support modules that need to obtain information about the local CPU environment (e.g. a traffic-shaping), the code can call this function: + +```java +cpuLoadAverageStats.getCpuLoadAverage(); // returns a float +``` + ### Configuration It's possible to define default module configuration which can be read by the module at PBS startup. Please see the [Configuration](https://docs.google.com/document/d/1VP_pi7L5Iy3ikHMbtC2_rD5RZTVSc3OkTWKvtRS5x5Y/edit#heading=h.mh3urph3k1mk) section of the technical specification. @@ -211,7 +225,7 @@ Analytics adapters can receive these tags in a parameter that's been added to th To get analytics tag you need to go into: -``` +```text AuctionEvent -> AuctionContext -> HookExecutionContext @@ -221,11 +235,10 @@ AuctionEvent -> analyticsTags ``` -The AnalyticsTags object has activities with collection of org.prebid.server.hooks.v1.analytics.Result objects inside. Each Result has the values() method which returns com.fasterxml.jackson.databind.node.ObjectNode. +The AnalyticsTags object has activities with collection of org.prebid.server.hooks.v1.analytics.Result objects inside. Each Result has the values() method which returns com.fasterxml.jackson.databind.node.ObjectNode. It depends on the particular module implementation how to parse their analytics tags, since the internal structure is custom and depends on the module. Therefore, analytics modules that want to report on specific behavior need to be coded to know about that module. See the ortb2blocking module for an example of what analytics tags may be available. - ## Further Reading - [PBS Module Overview](/prebid-server/developers/add-a-module.html)