OpenRTB: Allow model inheritance from external packages

docs/developers/openrtb-model-inheritance.md

@@ -0,0 +1,36 @@
+# Extending OpenRTB models
+
+Applications that use Prebid Server Java as a JAR dependency can subclass the models in
+`com.iab.openrtb.request` and `com.iab.openrtb.response` from their own packages. This includes the nested OpenRTB and
+Native Ads objects, so an integration can extend individual parts of a request or response as well as the root object.
+
+This is useful when reusing bidder adapters in an application that has its own request and response representation.
+A subclass can carry local context or implement application-specific behavior while remaining assignable to the concrete
+OpenRTB types accepted by existing APIs. Without inheritance, an unrelated wrapper cannot be passed to those APIs;
+integrations must construct the Prebid model or maintain a modified copy of it.
+
+The value classes retain their private final fields and existing builders. Their all-arguments constructors are protected
+for use by subclasses, and the existing `of(...)` factories remain available. `BrandVersion` retains its existing public
+constructor. The already extensible `Native` class retains its constructors and builder.
+
+For example, a response subclass can initialize the inherited state from an existing response:
+
+```java
+public class ApplicationBidResponse extends BidResponse {
+
+    public ApplicationBidResponse(BidResponse response) {
+        super(response.getId(), response.getSeatbid(), response.getBidid(), response.getCur(),
+                response.getCustomdata(), response.getNbr(), response.getExt());
+    }
+}
+```
+
+Subclassing does not change the behavior of the generated builders: `build()` and `toBuilder().build()` produce the
+declared model type, not the application's subtype. In particular, generated `toBuilder()` methods copy backing fields,
+so overriding getters alone does not implement a lazy or copy-on-write proxy. Builder inheritance and change tracking
+are outside the scope of this extension point. Custom accessors used by equality, such as `Imp.bidFloor()`, may also read
+backing fields directly. Subclasses must account for this when overriding getters or equality.
+
+Applications are responsible for their subclasses' serialization, equality and state ownership. Additional getters can
+become JSON properties, and mutable collections or extension nodes are not made immutable by inheritance. Constructor
+signatures follow the model fields, so subclasses may need to be updated when upgrading the dependency.

src/main/java/com/iab/openrtb/request/App.java

@@ -1,7 +1,10 @@
 package com.iab.openrtb.request;
 
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 import org.prebid.server.proto.openrtb.ext.request.ExtApp;
 
 import java.util.List;
@@ -14,6 +17,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class App {
 
     /**

src/main/java/com/iab/openrtb/request/Asset.java

@@ -1,11 +1,16 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Asset {
 
     public static final Asset EMPTY = Asset.builder().build();

src/main/java/com/iab/openrtb/request/Audio.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.math.BigDecimal;
 import java.util.List;
@@ -23,6 +26,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Audio {
 
     /**

src/main/java/com/iab/openrtb/request/Banner.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.util.List;
 
@@ -23,6 +26,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Banner {
 
     /**

src/main/java/com/iab/openrtb/request/BidRequest.java

@@ -1,7 +1,10 @@
 package com.iab.openrtb.request;
 
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 import org.prebid.server.proto.openrtb.ext.request.ExtRequest;
 
 import java.util.List;
@@ -20,6 +23,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class BidRequest {
 
     /**

src/main/java/com/iab/openrtb/request/BrandVersion.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.util.List;
 
@@ -12,6 +13,7 @@
  * platform or operating system.
  */
 @Value
+@NonFinal
 public class BrandVersion {
 
     /**

src/main/java/com/iab/openrtb/request/Channel.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 /**
  * This object describes the channel an ad will be displayed on. A
@@ -16,6 +19,8 @@
  */
 @Builder
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Channel {
 
     /**

src/main/java/com/iab/openrtb/request/Content.java

@@ -2,8 +2,11 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.util.List;
 
@@ -18,6 +21,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Content {
 
     private static final Content EMPTY = Content.builder().build();

src/main/java/com/iab/openrtb/request/Data.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.util.List;
 
@@ -16,6 +19,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Data {
 
     /**

src/main/java/com/iab/openrtb/request/DataObject.java

@@ -1,11 +1,16 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class DataObject {
 
     Integer type;

src/main/java/com/iab/openrtb/request/Deal.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.math.BigDecimal;
 import java.util.List;
@@ -15,6 +18,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Deal {
 
     /**

src/main/java/com/iab/openrtb/request/Device.java

@@ -1,7 +1,10 @@
 package com.iab.openrtb.request;
 
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 import org.prebid.server.proto.openrtb.ext.request.ExtDevice;
 
 import java.math.BigDecimal;
@@ -26,6 +29,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Device {
 
     /**

src/main/java/com/iab/openrtb/request/Dooh.java

@@ -1,7 +1,10 @@
 package com.iab.openrtb.request;
 
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 import org.prebid.server.proto.openrtb.ext.request.ExtDooh;
 
 import java.util.List;
@@ -13,6 +16,8 @@
  */
 @Value
 @Builder(toBuilder = true)
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Dooh {
 
     /**

src/main/java/com/iab/openrtb/request/DurFloor.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.math.BigDecimal;
 
@@ -11,6 +14,8 @@
  */
 @Value
 @Builder
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class DurFloor {
 
     /**

src/main/java/com/iab/openrtb/request/Eid.java

@@ -1,13 +1,18 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.util.List;
 
 @Value
 @Builder(toBuilder = true)
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Eid {
 
     String source;

src/main/java/com/iab/openrtb/request/EventTracker.java

@@ -1,13 +1,18 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 import java.util.List;
 
 @Builder
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class EventTracker {
 
     Integer event;

src/main/java/com/iab/openrtb/request/Format.java

@@ -1,8 +1,11 @@
 package com.iab.openrtb.request;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 
 /**
  * This object represents an allowed size (i.e., height and width combination)
@@ -13,6 +16,8 @@
  */
 @Builder
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Format {
 
     /**

src/main/java/com/iab/openrtb/request/Geo.java

@@ -1,7 +1,10 @@
 package com.iab.openrtb.request;
 
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Value;
+import lombok.experimental.NonFinal;
 import org.prebid.server.proto.openrtb.ext.request.ExtGeo;
 
 /**
@@ -16,6 +19,8 @@
  */
 @Builder(toBuilder = true)
 @Value
+@NonFinal
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 public class Geo {
 
     public static final Geo EMPTY = Geo.builder().build();