Prime Radiant Online

Welcome to our Normalized Systems online documentation, located in the “Prime Radiant @ Star’s End”. This is where you will find all the information needed to use Normalized Systems.

If you want to contribute to this documentation, be sure to read the documentation how to, and the todo list

Latest stable release: 2020.1.0

Upgrade to Struts 2.5


Expanders 4.2.0+ will use Struts 2.5. Also required for this are baseComponents 2020.2.0+ and nsx-runtime 2020.2.0+ (provided by prime-data 2020.2.0+).

The reason for the upgrade is security, as previous versions of struts contain critical vulnerabilities:

https://nvd.nist.gov/vuln/detail/CVE-2018-1327

Artifacts Changed

Expanders:

  • web.xml (updated package for StrutsPrepareAndExecuteFilter)
  • struts xml files (updated dtd reference)

baseComponents:

  • AccessInfoRetrieverAction (ActionContext::getParameters() has a different return type)

nsx-runtime

  • TranslateTextAction (Uses StrutsLocalizedTextProvider instead of LocalizedTextUtil)

Infrastructure

TomEE 7.0.4

Old apache-commons-lang3 library throws java.lang.NoSuchMethodError. Upgrade TomEE to version 7.1.1+ or manually update lib/commons-lang3-3.5.jar to lib/commons-lang3-3.8.1.jar.

Custom Code

Listing of known issues encountered during migrations and how to fix them.

ActionSupport.LOG

Custom struts actions using LOG of com.opensymphony.xwork2.ActionSupport, possibly due to copy-pasting.

Fix: Create class-specific logger.

// old code
class MyStrutsAction extends ActionSupport {
  public String execute() {
    LOG.info("...");
  }
}

// replacement code
class MyStrutsAction extends ActionSupport {
  private Logger logger = LoggerFactory.getLogger(MyStrutsAction.class);
  public String execute() {
    logger.info("...");
  }
}

Overriding Parameters in Struts Interceptors

// old code
ActionContext.getContext().getParameters().put($key$, $value$);

// replacement code (for structural replace)
java.util.Map<String, org.apache.struts2.dispatcher.Parameter> newParams = new java.util.HashMap<String, org.apache.struts2.dispatcher.Parameter>();
newParams.put($key$, new org.apache.struts2.dispatcher.Parameter.Request($key$, $value$));
ActionContext.getContext().getParameters().appendAll(newParams);

Directly invoking LocalizedTextUtil

Replacements can be applied via IntelliJ’s Structural Replace action.

LocalizedTextTranslator is available in nsx-runtime/nsx-presentation-struts2 v2020.4.0+

// old code
LocalizedTextUtil.findDefaultText($KEY$, $LOCALE$)

// replacement code within StrutsAction with current locale
getText($KEY$)

// replacement code within StrutsAction with DIFFERENT locale
net.democritus.utils.LocalizedTextTranslator.findText(getContainer(), $KEY$, $LOCALE$)

// replacement code outside of StrutsAction
net.democritus.utils.LocalizedTextTranslator.findText($KEY$, $LOCALE$)

// hand-constructed replacement directly invoking/dependning on struts classes
Container container = ServletActionContext.getContext().getContainer();
LocalizedTextProvider localizedTextProvider = container.getInstance(com.opensymphony.xwork2.LocalizedTextProvider.class);
String value = localizedTextProvider.findText(TextProviderSupport.class, $KEY$, $LOCALE$, (String)null, new Object[0]);

https://cwiki.apache.org/confluence/display/WW/Struts+2.3+to+2.5+migration


Using Expansion-resources in PR


Expansion-resources (or expander bundles) are jars with additional expanders, features or other data the expanders can use to generate additional files or add additional code to existing artifacts.

These expansion resources often encapsulate a new concern, e.g. the rest-expanders generate classes which will expose a REST interface based on JaxRS.

New Expansion Control dashboard

In version 2020.2.0 of the Prime Radiant, it will be possible to add expansion-resources to an applicationInstance and to then use them during expansion.

The applicationInstance page has been replaced with the (very similar) expansion/control page. The links throughout the application have been updated:

dashboard link

However, you might still notice the different url being used /primeRadiant/expansionControl/expansion/control instead of /primeRadiant/elements/applicationInstance/all.

The /primeRadiant/elements/applicationInstance/all is still available for this version, should any problems arise.

Expansion Resources

On the expansion control page, you will find an Expansion Resources tab. In this tab, there is a list of all expansion-resources and an input field to add new expansion resource:

expansion resource 0

If the expansion resource does not exist yet, the PR will ask whether you wish to add it to the database. If confirmed, the expansion-resource will be added and stored to use in the future.

expansion resource 1

expansion resource 2


Expanders Docs moved to exchange.stars-end.net


The auto-generated documentation on the Expanders and various other expander bundles, has been moved to exchange.stars-end.net.

The exchange site is, similar to this documentation, based on Jekyll and can be found in its own repository (normalizedsystems/exchange-docs).

The goal is to make a dedicated page to share expander bundles and hopefully provide some useful documentation. At the moment, the automatically generated documentation can seem a bit rough. We will continue to update the report-expanders to improve the insight into the expander bundles and allow for better integration with existing documentation.


Update to Jekyll


The documentation has been updated to use Jekyll as documentation engine.

There were several reasons to change:

  • Gitbook was no longer being developed
  • The build was starting to get slow because the gitbook build does not scale well
  • Each new article needed to be added manually to the SUMMARY file, which also introduces issues with scalability.

Jekyll is based on Ruby. So if you wish to build it locally you will have to install Ruby (follow instructions on Jekyll website).

We are using a variant on the Docsy Theme.

There are a few differences with Gitbook:

  • There is no SUMMARY file that needs to be kept in sync. Just drop your article in the _docs directory (and preferably link to it from another page).
  • The root articles for a directory are named index.md instead of README.md.
  • Absolute links need to be prefixed with ``
  • Links should point to the url, not the .md file