Package io.unlaunch

Interface UnlaunchClient

All Superinterfaces:
java.lang.Cloneable
All Known Implementing Classes:
OfflineUnlaunchClient
public interface UnlaunchClient
extends java.lang.Cloneable

Client for accessing Unlaunch. Provides all features for accessing and evaluating features flags setup through the Unlaunch web console i.e. https://app.unlaunch.io). UnLaunch is an enterprise-grade feature flags platform inspired by the way you ship features. Deploy your features to production more frequently and with confidence.

Sample code to get you started:

     UnlaunchClient client = UnlaunchClient.create("your sdk key");

     String variation = client.getVariation("flagKey", "userId123");
     if (variation == "on") {
         System.out.println("Variation is on");
     } else if (variation == "off") {
         System.out.println("Variation is off");
     } else {
         System.out.println("no variation");
     }

     client.shutdown();

This is the server-side SDK which means it will download all feature flags and associated data upon initialization (and periodically based on settings.)

Creating a new client can be an expensive operation and should only be done once and shared in an application The close() method needs to be called on the client object to clean up resources such as threads during application shutdown. To create clients, you can use the create methods such as create(String) or using the static builder() method which returns UnlaunchClientBuilder which can be used to customize the client.

Author:
umer mansoor
See Also:
https://unlaunch.io

  • Method Summary

    Modifier and Type Method Description
    AccountDetails accountDetails()
    Returns account details for the Unlaunch project and environment the client is connected to.
    void awaitUntilReady​(long timeout, java.util.concurrent.TimeUnit unit)
    Causes the current thread to wait until UnlaunchClient is initialized, unless the thread is interrupted, or the specified waiting time elapses.
    static UnlaunchClientBuilder builder()
    Create a builder that can be used to customize and create a UnlaunchClient.
    static UnlaunchClient create()
    Create a UnlaunchClient with the SDK key loaded from the UNLAUNCH_SDK_KEY environment variable.
    static UnlaunchClient create​(java.lang.String sdkKey)
    Constructs an instance of the UnlaunchClient using the given SDK key.
    UnlaunchFeature getFeature​(java.lang.String flagKey, java.lang.String identity)
    Same as getVariation(String, String) but returns a UnlaunchFeature object that contains the evaluated variation (variation key) and any configuration (key, value properties or JSON) associated with the evaluated variation, defined in the Unlaunch web console.
    UnlaunchFeature getFeature​(java.lang.String flagKey, java.lang.String identity, UnlaunchAttribute... attributes)
    Same as getFeature(String, String) but uses attributes that are passed as argument when evaluating the feature flag's targeting rules.
    java.lang.String getVariation​(java.lang.String flagKey, java.lang.String identity)
    Evaluates and returns the variation (variation key) for this feature.
    java.lang.String getVariation​(java.lang.String flagKey, java.lang.String identity, UnlaunchAttribute... attributes)
    Same as getVariation(String, String) but uses attributes that are passed as argument when evaluating the feature flag's targeting rules.
    boolean isReady()
    Returns true is the client is intialized and ready.
    void shutdown()
    Closes the client by cleaning up all resources such as in memory caches, etc., stops running tasks and rejects any new requests which arrive after this method is called.

  • Method Details

    • create

      static UnlaunchClient create()
      Create a UnlaunchClient with the SDK key loaded from the UNLAUNCH_SDK_KEY environment variable.
      Returns:
      UnlaunchClient

    • create

      static UnlaunchClient create​(java.lang.String sdkKey)
      Constructs an instance of the UnlaunchClient using the given SDK key.
      Parameters:
      sdkKey - - SDK key for your Unlaunch project.
      Returns:
      A new client

    • builder

      static UnlaunchClientBuilder builder()
      Create a builder that can be used to customize and create a UnlaunchClient.
      Returns:
      UnlaunchClientBuilder

    • accountDetails

      AccountDetails accountDetails()
      Returns account details for the Unlaunch project and environment the client is connected to.
      Returns:
      AccountDetails

    • getVariation

      java.lang.String getVariation​(java.lang.String flagKey, java.lang.String identity)
      Evaluates and returns the variation (variation key) for this feature. Variations are defined using the Unlaunch Console at https://app.unlaunch.io.

      This method returns "control" if:

      1. The flag was not found.
      2. There was an exception evaluation the feature flag.
      3. The flag was archived.

      This method doesn't throw any exceptions nor does it return null value

      Parameters:
      flagKey - the feature flag you want to evaluate.
      identity - unique id of your user or a unique identifier such as request or session id, email, etc. It may be null but 'Percentage rollout' will not work because it is used to determine bucketing. If this is null and 'Percentge rollout' is enabled, we'll log exceptions in your code and also in the Unlaunch web app.
      Returns:
      the evaluated variation or "control" if there was an error.

    • getVariation

      java.lang.String getVariation​(java.lang.String flagKey, java.lang.String identity, UnlaunchAttribute... attributes)
      Same as getVariation(String, String) but uses attributes that are passed as argument when evaluating the feature flag's targeting rules. Targeting rules are defined on the Unlaunch web console. To understand attributes, suppose you have defined a feature flag with targeting rules to return certain variation based on user's country e.g. 
            if country is "USA" AND subscriber is true
          return "on"
      otherwise
          return "off"
      In this example, country will be subscriber are attributes that must be passed in. If the user is from USA and is subscriber, the "on" variation will be returned. Otherwise, "off". 
        client.getFeature(
     "show_bonus_pack",
     userId,
     UnlaunchAttribute.newString("country", "USA"),
     UnlaunchAttribute.newBoolean("sbscriber", true)
  );

      This method doesn't throw any exceptions nor does it return null value

      Parameters:
      flagKey - the feature flag you want to evaluate.
      identity - unique id of your user or a unique identifier such as request or session id, email, etc. It * may be null but 'Percentage rollout' will not work because it is used to determine bucketing. * If this is null and 'Percentge rollout' is enabled, we'll log exceptions in your code and also * in the Unlaunch web app.
      attributes - attributes to apply when evaluating target rules.
      Returns:
      the evaluated variation or "control" if there was an error.

    • getFeature

      UnlaunchFeature getFeature​(java.lang.String flagKey, java.lang.String identity)
      Same as getVariation(String, String) but returns a UnlaunchFeature object that contains the evaluated variation (variation key) and any configuration (key, value properties or JSON) associated with the evaluated variation, defined in the Unlaunch web console. For example, to get dynamic configuration associated with a variation, you can: 
            UnlaunchFeature feature = client.getFeature("new_login_ui", userId);
      String colorHexCode = feature.getVariationConfig().getString("login_button_color", "#cd5c5c");

      renderButton(colorHexCode);
      Parameters:
      flagKey - the feature flag you want to evaluate.
      identity - unique id of your user or a unique identifier such as request or session id, email, etc. It may be null but 'Percentage rollout' will not work because it is used to determine bucketing.
      Returns:
      UnlaunchFeature object that contains evaluated variation key, configuration and evaluation reason.

    • getFeature

      UnlaunchFeature getFeature​(java.lang.String flagKey, java.lang.String identity, UnlaunchAttribute... attributes)
      Same as getFeature(String, String) but uses attributes that are passed as argument when evaluating the feature flag's targeting rules. Targeting rules are defined on the Unlaunch web console. To understand attributes, suppose you have defined a feature flag with targeting rules to return certain variation based on user's country e.g. 
            if user's country is "USA" AND device is "handheld"
          return "on"
      otherwise
          return "off"
      In this example, country will be device are attributes that must be passed in.
      Parameters:
      flagKey - the feature flag you want to evaluate.
      identity - unique id of your user or a unique identifier such as request or session id, email, etc. It may be null but 'Percentage rollout' will not work because it is used to determine bucketing.
      attributes - an array of attributes to evaluate against
      Returns:
      UnlaunchFeature object that contains evaluated variation key, configuration and evaluation reason.

    • awaitUntilReady

      void awaitUntilReady​(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException, java.util.concurrent.TimeoutException
      Causes the current thread to wait until UnlaunchClient is initialized, unless the thread is interrupted, or the specified waiting time elapses.

      If the current thread:

      • has its interrupted status set on entry to this method; or
      • is interrupted while waiting,

      then InterruptedException is thrown and the current thread's interrupted status is cleared.

      Parameters:
      timeout - the maximum time to wait
      unit - the time unit of the timeout argument
      Throws:
      java.lang.InterruptedException - if the current thread is interrupted while waiting
      java.util.concurrent.TimeoutException - if it times out before initialization is complete

    • isReady

      boolean isReady()
      Returns true is the client is intialized and ready. False otherwise.

      Initialized means that the client was able to download flags and data from the Unlaunch server at leasr once.

      Returns:

    • shutdown

      void shutdown()
      Closes the client by cleaning up all resources such as in memory caches, etc., stops running tasks and rejects any new requests which arrive after this method is called.

      The default behavior of this method is to block until everything has been shutdown or it encountered an error or timed out (usually a few seconds.)