Skip to content

Beta Fencing

Jump to bottom
Zach Hein edited this page Nov 20, 2024 · 2 revisions

Primary Beta Fencing Options

  1. This is a new Open Liberty feature which will be marked kind=noship or kind=beta.
  2. A new high-level config element is being added to enable this feature and will be marked as “ibm:beta” in the metatype.
  3. A new config attribute in an existing element is being added to enable this feature and will be marked as “ibm:beta” in the metatype.
  4. Use the Beta Edition JVM Property to fence the beta method (example in following guide).

Beta config elements

The ibm:beta="true" property can be added to either top-level configuration elements or new properties within existing elements. e.g.

<OCD id="io.openliberty.myNewComponent" ibm:alias="myNewComponent" name="%myNewComponent" description="%myNewComponent.desc" ibm:beta="true">
  <AD id="myProperty" type="Integer" default="0" min="0" name="%myProperty" description="%myProperty.desc"/>
</OCD>

OR

<OCD id="io.openliberty.myComponent" ibm:alias="myComponent" name="%myComponent" description="%myComponent.desc">
  <AD id="myNewProperty" type="Integer" default="0" min="0" name="%myNewProperty" description="%myNewProperty.desc" ibm:beta="true"/>
</OCD>

Configuration elements and properties will not appear in the generated server.xml schema but they can still be specified and will still work in a GA release. Therefore, CAUTION must be used if the presence of the configuration will change the behaviour of the code. In the example above, a default value was provided, so the configuration will always appear to exist at runtime even if the user did not specify it in the server.xml.

  • It is highly recommended that any runtime code in existing GA features which uses beta configuration is also guarded using the JVM System Property...

Beta Fencing using JVM System Property

In project com.ibm.ws.kernel.boot.core, there is code to set a system property called com.ibm.ws.beta.edition. This property tells us if the server edition is EARLY_ACCESS or not. This property is set on server startup.

The rules for beta fencing API and/or SPI method code using this option are:

  1. Marking the function @Deprecated
  2. Issuing a message if a beta method is called the first time a beta method is called for a class.
  3. Throw a UnsupportedOperationException

The rules for beta fencing support for using a new OSGi whiteboard service registration are:

  1. Ignore service registrations when not beta enabled.
  2. Issuing a message if a beta whiteboard service is called the first time a beta whiteboard service is called.

With the com.ibm.ws.beta.edition system property set, we can now check if we are running a beta edition by checking the beta system property and add code to handle calls to the method based on how the property is set. If it is true, we issue a message saying there has been a call to a beta method if its the first time a beta method is called for the class and let the method run normally. If it is false, we throw an UnsupportedMethodException with a message.

Example using ProductInfo.getBetaEdition()

// Flag tells us if the message for a call to a beta method has been issued
private static boolean issuedBetaMessage = false;

private void betaFenceCheck() throws UnsupportedOperationException {
    // Not running beta edition, throw exception
    if (!ProductInfo.getBetaEdition()) { 
        throw new UnsupportedOperationException("This method is beta and is not available.");
    } else {
    // Running beta exception, issue message if we haven't already issued one for this class
        if (!issuedBetaMessage) {
            Tr.info(tc, "BETA: A beta method has been invoked for the class " + this.getClass().getName() + " for the first time.");
            issuedBetaMessage = !issuedBetaMessage;
       }
    }
}

// Call the code to handle the beta fencing at the beginning of the method that is being beta fenced.
// Mark it deprecated so javadocs are not published
@Deprecated 
public void foo() {
   betaFenceCheck();
}

Add the following to bnd.bnd under build-path: com.ibm.ws.kernel.boot.core;version=latest

Running FAT Tests with Beta Fenced Method

Create a jvm.options file in your server directory and add the following argument: -Dcom.ibm.ws.beta.edition=true. When the FAT test runs, the server will start with beta methods enabled.

Note that adding this property to bootstrap.properties will not work since the server will set this property if it's unset before it reads bootstrap.properties.

Troubleshooting

If you see java.lang.NoClassDefFoundError: com.ibm.ws.kernel.productinfo.ProductInfo or java.lang.ClassNotFoundException: com.ibm.ws.kernel.productinfo.ProductInfo.
Then you need to - Add the following to bnd.bnd under build-path: com.ibm.ws.kernel.boot.core;version=latest

Clone this wiki locally