isis-module-togglz

Table of Contents

• Screenshots
  • Login as administrator
  • Feature disabled
  • Togglz Console
  • Feature enabled
  • Feature persistence
• How to run the Demo App
• Service SPIs
• How to configure/use
  • "Out-of-the-box"
  • "Out-of-the-box" (-SNAPSHOT)
  • Forking the repo
• Related Modules/Services
• Change Log
• Legal Stuff
  • License
  • Dependencies
• Maven deploy notes
  • Release to Sonatype’s Snapshot Repo
  • Release an Interim Build
  • Release to Maven Central

This module, intended for use with Apache Isis, provides an integration with Togglz to provide a feature toggle capability.

Courtesy of Togglz, this integration has an embedded console and has support for integration testing through a custom JUnit rule.

The module integrates both Togglz and uses Isis Addons' settings module for feature persistence.

Screenshots

The following screenshots show an example app’s usage of the module.

Login as administrator

Feature disabled

In the demo app the "Togglz Demo Objects" service has three actions, all of which are protected behind features. Two of these (for "create" and "listAll") are enabled by default, but one (for "findByName") is disabled by default, meaning that the action is suppressed from the UI:

Togglz Console

Users with the appropriate role (isis-module-togglz-admin) can access the Togglz console, which lists all features:

Using the console, we can edit the feature:

so it is now enabled:

Feature enabled

Back in the demo app the feature ("findByName") is now visible:

Feature persistence

The module uses Isis addons' settings module for feature persistence.

Each feature’s state is serialized to/from JSON:

How to run the Demo App

The prerequisite software is:

• Java JDK 8

  • note that the compile source and target is JDK 7

• maven 3 (3.2.x is recommended).

To build the demo app:

git clone https://github.com/isisaddons/isis-module-togglz.git
mvn clean install

To run the demo app:

mvn antrun:run -P self-host

Then log on using user: sven, password: pass

Service SPIs

The module defines the following SPI service that must be implemented:

public interface FeatureStateRepository {
    FeatureState find(String key);
    FeatureState create(String key);
}

where FeatureState is just a wrapper around a string:

public interface FeatureState {
    String getValue();
    void setValue(String value);
}

This is used to persist the feature state.

How to configure/use

You can either use this module "out-of-the-box", or you can fork this repo and extend to your own requirements.

"Out-of-the-box"

To use "out-of-the-box":

• update the classpath in your project’s dom module pom.xml to reference the togglz library:
  

  <properties>
      <togglz.version>2.1.0.Final</togglz.version>
  </properties>
  <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-core</artifactId>
      <version>${togglz.version}</version>
  </dependency>

• as described in the [Togglz documentation](http://www.togglz.org/documentation/overview.html), create a "feature enum" class that enumerates your features. This should extend from org.togglz.core.Feature.
  

  For example, the demo app’s feature enum class is:
  

  public enum TogglzDemoFeature implements org.togglz.core.Feature {
  
      @Label("Enable create")
      @EnabledByDefault
      create,
  
      @Label("Enable findByName")
      findByName,
  
      @Label("Enable listAll")
      @EnabledByDefault
      listAll;
  
      public boolean isActive() {
        return FeatureContext.getFeatureManager().isActive(this);
      }
  }

• use your feature class in your app as required.
  

  For example, the demo app uses its feature enum to selectively hide actions of the TogglzDemoObjects domain service:
  

  public class TogglzDemoObjects {
      ...
      public List<TogglzDemoObject> listAll() { ... }
      public boolean hideListAll() {
        return !TogglzDemoFeature.listAll.isActive();
      }
  }

• in your integtests module, update the pom.xml for togglz’s JUnit support:
  

  <dependency>
      <groupId>org.togglz</groupId>
      <artifactId>togglz-junit</artifactId>
      <scope>test</scope>
  </dependency>

• also in your integtests module, make sure that the TogglzRule (documented here on the togglz website) is enabled for any tests that depend on features.
  

  In the demo app, this means adding the following to TogglzModuleIntegTest base class:
  

  @Rule
  public TogglzRule togglzRule = TogglzRule.allEnabled(TogglzDemoFeature.class);

• update your classpath by adding this dependency in your project’s fixture module’s pom.xml:
  

  <dependency>
      <groupId>org.isisaddons.module.togglz</groupId>
      <artifactId>isis-module-togglz-glue</artifactId>
      <version>1.14.0</version>
  </dependency>
  <dependency>
      <groupId>org.isisaddons.module.security</groupId>
      <artifactId>isis-module-security-dom</artifactId>
      <version>1.14.0</version>                               <!--(1)-->
  </dependency>

  1. or which ever is the latest version

• in your project’s app module, write a subclass of TogglzModuleFeatureManagerProviderAbstract (provided by this module) that registers your feature enum:
  

  public class CustomTogglzModuleFeatureManagerProvider
        extends TogglzModuleFeatureManagerProviderAbstract {
      protected CustomTogglzModuleFeatureManagerProvider() {
        super(TogglzDemoFeature.class);
      }
  }

• also in your project’s app module, in src/main/resources, register the provider by creating a file META-INF/services/org.togglz.core.spi.FeatureManagerProvider. Its contents is the fully qualified class name of your feature manager provider implementation.
  

  For example, the demo app’s file consists of:
  

  org.isisaddons.module.togglz.webapp.CustomTogglzModuleFeatureManagerProvider

• also in your project’s app module, write an implementation of the FeatureStateRepository SPI service (defined by this module). This SPI service is designed to be easy to be implemented using the(non-ASF) Isis addons' settings module (though you can of course use some other persistence mechanism if you wish). For example:
  

  @DomainService(nature = NatureOfService.DOMAIN)
  public class FeatureStateRepositoryForApplicationSettingsJdo implements FeatureStateRepository {
      public FeatureState find(final String key) {
          final ApplicationSetting applicationSetting =
                                        applicationSettingsService.find(key);
          return FeatureStateForApplicationSettingJdo.from(applicationSetting);
      }
      public FeatureState create(final String key) {
          final ApplicationSetting applicationSetting =
                                        applicationSettingsService.newString(key, "", "");
          return FeatureStateForApplicationSettingJdo.from(applicationSetting);
      }
      @Inject
      ApplicationSettingsServiceRW applicationSettingsService;
  }

  and:

  class FeatureStateForApplicationSettingJdo implements FeatureState {
      static FeatureState from(final ApplicationSetting applicationSetting) {
          return applicationSetting != null ?
                      new FeatureStateForApplicationSettingJdo(applicationSetting) : null;
      }
      private final ApplicationSettingForJdo applicationSetting;
      private FeatureStateForApplicationSettingJdo(final ApplicationSetting applicationSetting) {
          this.applicationSetting = (ApplicationSettingForJdo) applicationSetting;
      }
      public String getValue() {
          return applicationSetting.valueAsString();
      }
      public void setValue(final String value) {
          applicationSetting.updateAsString(value);
      }
  }

• in your AppManifest, update its getModules() method.
  

  @Override
  public List<Class<?>> getModules() {
      return Arrays.asList(
              ...
              org.isisaddons.module.security.SecurityModule.class,
              org.isisaddons.module.settings.SettingsModule.class,
              org.isisaddons.module.togglz.TogglzModule.class,
              ...
      );
  }

• in your project’s webapp module, update your WEB-INF/web.xml, after the Shiro configuration but before Isis' configuration (so that the filters are applied in the order Shiro -> Togglz -> Isis):
  

  <!-- bootstrap Togglz -->
  <context-param>
      <param-name>org.togglz.FEATURE_MANAGER_PROVIDED</param-name>
      <!-- prevent the filter from bootstrapping
            so is done lazily later once Isis has itself bootstrapped -->
      <param-value>true</param-value>
  </context-param>
  <filter>
      <filter-name>TogglzFilter</filter-name>
      <filter-class>org.togglz.servlet.TogglzFilter</filter-class>
  </filter>
  <filter-mapping>
      <filter-name>TogglzFilter</filter-name>
      <url-pattern>/*</url-pattern>
  </filter-mapping>

• optional: if you want to install the Togglz console, then in your project’s webapp module, update your WEB-INF/web.xml:
  

  <!-- enable the togglz console (for FeatureToggleService) -->
  <servlet>
      <servlet-name>TogglzConsoleServlet</servlet-name>
      <servlet-class>org.togglz.console.TogglzConsoleServlet</servlet-class>
  </servlet>
  <servlet-mapping>
      <servlet-name>TogglzConsoleServlet</servlet-name>
      <url-pattern>/togglz/*</url-pattern>
  </servlet-mapping>

  The togglz console will be available at http://localhost:8080/togglz

• if you have configured the Togglz console (above), then you’ll also need to setup users to have isis-module-togglz-admin role.
  

  The demo app uses simple Shiro-based configuration, which means updating the WEB-INF/shiro.ini file, eg:
  

  sven = pass, admin_role, isis-module-togglz-admin

• if you have configured the Togglz console (above), then you can optionally configure its URL and also whether to hide the menu action provided to access the console from the main Wicket application:
  

  in isis.properties (or in AppManifest#getConfigurationProperties()):

  isis.services.togglz.FeatureToggleConsoleAccessor.consoleUrl=http:///togglz     #(1)
  isis.services.togglz.FeatureToggleConsoleAccessor.hideAction=false              #(2)

  1. URL that hosts the togglz console

  2. whether to hide the action that can be used to access the URL.

If you are using some other security mechanism, eg Isis addons security module, then define a role with the same name and grant to users. You can use the TogglzModuleAdminRole to setup fixture/seed data for the security module.

Note	Check for later releases by searching Maven Central Repo). Make sure the togglz.version defined in your dom module matches the one used in the version of the isis-module-togglz-glue module (currently 2.1.0.Final).

"Out-of-the-box" (-SNAPSHOT)

If you want to use the current -SNAPSHOT, then the steps are the same as above, except:

• when updating the classpath, specify the appropriate -SNAPSHOT version:
  

  <version>1.15.0-SNAPSHOT</version>

• add the repository definition to pick up the most recent snapshot (we use the Cloudbees continuous integration service). We suggest defining the repository in a <profile>:
  

      <profile>
          <id>cloudbees-snapshots</id>
          <activation>
              <activeByDefault>true</activeByDefault>
          </activation>
          <repositories>
              <repository>
                  <id>snapshots-repo</id>
                  <url>http://repository-estatio.forge.cloudbees.com/snapshot/</url>
                  <releases>
                      <enabled>false</enabled>
                  </releases>
                  <snapshots>
                      <enabled>true</enabled>
                  </snapshots>
              </repository>
          </repositories>
      </profile>

Forking the repo

If instead you want to extend this module’s functionality, then we recommend that you fork this repo. The repo is structured as follows:

• pom.xml - parent pom

• app - defines the app manifest

• glue - the module implementation, depends on Isis applib

• fixture - fixtures, holding a sample domain objects and fixture scripts; depends on dom

• integtests - integration tests for the module; depends on fixture

• webapp - demo webapp (see above screenshots); depends on dom and fixture

Only the glue project is released to Maven Central Repo. The versions of the other modules are purposely left at 0.0.1-SNAPSHOT because they are not intended to be released.

Related Modules/Services

This service uses the Isis Addons' settings module for feature persistence.

Change Log

• 1.14.0 - released against Isis 1.14.0

• 1.13.1 - introduced new (mandatory) ApplicationSettingsServiceMutable SPI service; released against Isis 1.13.2

• 1.13.0 - released against Isis 1.13.0

• 1.12.0 - released against Isis 1.12.0

• 1.11.0 - released against Isis 1.11.0; added FeatureTogglzConsoleAccessor service.

• 1.10.0 - released against Isis 1.10.0

• 1.9.0 - released against Isis 1.9.0

Legal Stuff

License

Copyright 2015-2016 Dan Haywood

Licensed under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Dependencies

There are no third-party dependencies.

Maven deploy notes

Only the dom module is deployed, and is done so using Sonatype’s OSS support (see user guide).

Release to Sonatype’s Snapshot Repo

To deploy a snapshot, use:

pushd dom
mvn clean deploy
popd

The artifacts should be available in Sonatype’s Snapshot Repo.

Release an Interim Build

If you have commit access to this project (or a fork of your own) then you can create interim releases using the interim-release.sh script.

The idea is that this will - in a new branch - update the dom/pom.xml with a timestamped version (eg 1.14.0.20170227-0738). It then pushes the branch (and a tag) to the specified remote.

A CI server such as Jenkins can monitor the branches matching the wildcard origin/interim/* and create a build. These artifacts can then be published to a snapshot repository.

For example:

sh interim-release.sh 1.14.0 origin

where

• 1.14.0 is the base release

• origin is the name of the remote to which you have permissions to write to.

Release to Maven Central

The release.sh script automates the release process. It performs the following:

• performs a sanity check (mvn clean install -o) that everything builds ok

• bumps the pom.xml to a specified release version, and tag

• performs a double check (mvn clean install -o) that everything still builds ok

• releases the code using mvn clean deploy

• bumps the pom.xml to a specified release version

For example:

sh release.sh 1.14.0 \
              1.15.0-SNAPSHOT \
              [email protected] \
              "this is not really my passphrase"

where * $1 is the release version * $2 is the snapshot version * $3 is the email of the secret key (~/.gnupg/secring.gpg) to use for signing * $4 is the corresponding passphrase for that secret key.

Other ways of specifying the key and passphrase are available, see the `pgp-maven-plugin’s documentation).

If the script completes successfully, then push changes:

git push origin master && git push origin 1.14.0

If the script fails to complete, then identify the cause, perform a git reset --hard to start over and fix the issue before trying again. Note that in the dom’s `pom.xml the nexus-staging-maven-plugin has the autoReleaseAfterClose setting set to true (to automatically stage, close and the release the repo). You may want to set this to false if debugging an issue.

According to Sonatype’s guide, it takes about 10 minutes to sync, but up to 2 hours to update search.