CommunityCommons

This module adds a number reusable Java methods to your project, which can be called from Microflows or custom Java actions. The content of this module is the result of many questions and answers posted at mxforum.mendix.com, and investigating several project. The module addes functionality for working with Dates, Batches, Strings, Internet, Files, Configuration etc. See the documentation or screenshot for a complete list of functions.

Description

This module adds many reusable java methods to your project, which can be called from microflows or custom java actions. The content of this module is the result of many questions and answers posted at mxforum.mendix.com, and investigating several project.

The module adds functionality for working with Dates, Batches, Strings, Internet, Files, Configuration etc. See the documentation or screenshot for a complete list of functions.

Important when updating ⚠️

Deprecated function removal

The RegexTest function was already deprecated for some time because you can use the isMatch() function in microflow expressions instead. In version 8.0.1, we removed this function.

Deleting obsolete dependencies first

It is highly recommended that you remove all jars that have an accompanying .CommunityCommons.RequiredLib file from the userlib folder by hand before importing the CommunityCommons 7.2.0 (or higher) module in the Modeler. Otherwise you may encounter strange compilation or runtime errors.

Java 8

This release utilizes some Java 8 native APIs that replace functionality that was previously imported from external libraries. This means that for upgrading, Java 8 is a minimum requirement! You can change your JDK directory in the Desktop Modeler under Edit > Preferences. For Mendix 8, AdoptOpenJDK 11 will be supported.

Breaking change to XSSSanitize

In order to mitigate some security vulnerabilities in dependent libraries, in version 7.2.0 the XSSSanitize action has been re-implemented using the OWASP Java HTML Sanitizer library. This means that any usage of this action in your app needs to be reconfigured. It now takes six policy parameters, of which at least one must be non-empty. Make sure that the non applicable policy parameters are explicitly filled in with the value empty. Possible policy values are defined in the SanitizerPolicy enumeration. The meaning of the policies are defined in the javadocs.

Usage

All functions in this package can be invoked using a microflow Java action call in a Microflow, our from your own java code by calling

communitycommons.<Action Folder>.<Action name>;

for example : commonitycommons.StringUtils.hash("Mendix", 20);

The module contains one constant: CommunityCommons.MergeMultiplePdfs_MaxAtOnce. It is used in the MergeMultiplePdfs Java action to restrict the number of PDFs processed at the same time. Restricted to 10 files at once for Mendix Cloud v4 compatibility. If you need to merge more than 10 files increase the number here. Setting the value to <= 0 means unlimited.

Testing

The Community Commons container project contains a variety of predesigned unit tests. To be able to use these tests the UnitTesting module should be downloaded from the AppStore. Please refer to the UnitTesting documentation for further instruction regarding the implementation. The UnitTesting has a dependency to the ObjectHandling module, so that module should also be imported to this project if you want to run the tests.

Contributing

For more information on contributing to this repository visit Contributing to a GitHub repository!

Gradle

In version 7.2.0, we introduce a new way of dependency management using a Gradle build file. Unfortunately, this doesn't mean that obsoleted jars are automatically deleted from your projects' userlib folder when you import the Community Commons module into your app model.

To download the dependencies and copy them to the userlib/ folder of the Community Commons container project, execute:

gradle prepareDeps

from the command line. Afterwards, you will be able to export a CommunityCommons.mpk module from the Community Commons main project. Select only the dependencies listed below as dependencies in userlib for the exported module.

Dependencies

For security reasons, Guava was upgraded to version 27 in Community Commons v7.4.0. This unfortunately means a number of new required jars in the userlib folder.

animal-sniffer-annotations-1.17.jar
checker-qual-2.5.2.jar
commons.io-2.6.jar
commons.lang3-3.7.jar
error-prone-annotations-2.2.0.jar
j2objc-annotations-1.1.jar
jsr305-3.0.2.jar
pdfbox-2.0.13.jar
fontbox-2.0.13.jar
guava-27.0-jre.jar
owasp-java-html-sanitizer-20181114.1.jar

Function list

Batches

RecommitInBatches - Given an XPath and a batch size, commit all matching objects in batches of the given size.

DeleteAll - Removes ALL instances of a certain domain object type using batches.

DateTime

DateTimeToLong - Converts a DateTime to a Unix timestamps (Milliseconds since 1-1-1970).

LongToDateTime - Converts a Unix timestamp(ms) to a dateTime object.

YearsBetween - Calculates the number of years between two dates.

MonthsBetween - Calculates the number of months between two dates.

GetIntFromDateTime - Extracts a part of a date (year, month or day) to an integer (new in 2.2).

Files

Base64DecodeToFile - Stores an base 64 encoded string plain in the provided target file document.

Base64EncodeFile - Converts an unencode file to a base 64 encoded string.

StringToFile - Stores a string into the provides filedocument. Supports multiple encodings since 7.4.1.

StringFromFile - Reads the contents form the provided file document and return it as string. Supports multiple encodings since 7.4.1.

StoreURLToFileDocument - Retrieve a document from an URL using a HTTP GET request.

DuplicateFileDocument - Clones the contents of one file document into another.

GetFileSize - Returns the filesize of a file document in bytes.

OverlayPdfDocument - Overlay a generated PDF document with another PDF (containing the company stationary for example)

Logging

CreateLogNode - Initialize a log node without having a log line.

TimeMeasureStart - Start timing something, and print the result to the log.

TimeMeasureEnd - End timing something, print the result to the log, and return the time taken in milliseconds.

Misc

AssertTrue - Shorthand for checking something, and throwing an error if that something is not true. Saves creating three microflow items for things that MUST be true.

CreateUserIfNotExists - (Microflow) Create a user with predefined password an role. Useful during startup for integration purposes. Changed in 2.4: The user now always gets updated, if even the user already exists.

Delay - Causes this request to sleep for a number of milliseconds. Useful to prevent brute force attacks or to simulate latency delays.

GetCFInstanceIndex - Returns the Cloud Foundry Instance Index that is set during deployment of the application in a Cloud native environment. Returns 0 for the leader instance, 1 or higher for slave instances or -1 when the environment variable could not be read (when running locally or on premises).

GetApplicationUrl - Returns the runtime URL of this application (without trailing slash).

GetRuntimeVersion - Returns the runtime version of this application.

RetrieveURL - Retrieves data (such as an HTML page) from an URL using the HTTP protocol, and returns it as string.

ThrowException - This action always throws an exception (of type communityutils.UserThrownError), which is, in combination with custom error handling, quite useful to end a microflow prematurely or to bail out to the calling action/ microflow.

ThrowWebserviceException - Throws an exception. This is very useful if the microflow is called by a webservice. If you throw this kind of exceptions, a fault message will be generated in the output, instead of an '501 Internal server' error. (Fixed/ updated in 2.2)

GetDefaultLanguage - Gets the Language object for the default language as defined in the model.

Execute Microflow

executeMicroflowAsUser - Executes the given microflow as if the $currentuser is the provided user (delegation).

RunMicroflowAsyncInQueue - Runs a microflow asynchronous, that is, this action immediately returns but schedules the microflow to be run in the near future. The queue guarantees a first come first serve order of the microflows, and only one action is served at a time. The microflow is run with system rights in its own transaction, and is very useful to run heavy microflows on the background.

executeMicroflowInBackground - Similar to RunMicroflowAsyncInQueue, but accepts one argument as parameter.

executeMicroflowInBatches (Recommended!) - Performs a batch operation on a large dataset, by invoking the microflow on small subsets of the data, each with its own database transaction.

recommitInBatches - Recommits (with events) all items returned by the xpath query. Useful in migration scenerios.

ORM

CommitWithoutEvents - Commits an object, but without events.

Clone - Clones objects

DeepClone - Clones objects, their associations and even referred objects.

GetGUID - returns the Global Unique Identifier (GUID, or id) of an object.

GetOriginalValueAsString - Returns the original value of an object member, that is, the last committed value.

GetTypeAsString - Returns the actual type of an Entity. Useful as alternative way to split upon inheritance, or as input of other functions in this module.

MemberHasChanged - Checks whether a member has changed since the last commit. Useful in combination with getOriginalValueAsString.

RefreshClass - Refreshes a certain domain object type in the client. Useful to enforce a datagrid to refresh for example.

refreshClassByObject - Refreshes a certain domain object type in the client. Useful to enforce a datagrid to refresh for example.

getLastChangedByUser - Returns the user that last changed an object as System.User.

getCreatedByUser - Returns the user that created an object.

encryptMemberIfChanged - Use this function to automatically encrypt attributes of an object during (for example) before commit. (new in 2.4)

EndTransaction - Commit the transaction, this will end this transaction or remove a save point from the queue if the transaction is nested.

StartTransaction - Start a transaction, if a transaction is already started for this context, a savepoint will be added.

Regexes

EmailAddressRegex - A, not too restrictive, email address regular expression.

GUIDOrEmpty - Same as GUIDRegex, but accepts empty string as well.

GUIDRegex - Supports alphanumeric characters, dash and underscore.

Identifier - Identifier.

StringUtils

Hash - Hashes a value using the SHA-256 hash algorithm.

HTMLEncode - Encodes a string to HTML Entities, so that they can be displayed in the browser without breaking any layout.

HTMLToPlainText - Use this function to convert HTML text to plain text. It will preserve linebreaks but strip all other markup. including html entity decoding.

IsStringSimplified - Whether a string can be further simplified by removing diacritics

RandomString - Generates a random alphanumeric string of the desired length.

RandomHash - Generates a random hash, perfectly to use as random, unique identifier.

RegexReplaceAll - Performs a regular expression replace. Works similarly to the microflow expression function 'replaceAll' but supports more constructs.

RegexQuote - Escapes a string value so that it can be used literally with Mendix built-in regex replacement functions. (Otherwise the dollar sign would be interpreted as back reference to a match for example).

RemoveEnd - Removes a string from the end of another string, if present

StringLeftPad - Pads a string on the left to a certain length.

StringRightPad - Pads a string on the right to a certain length.

StringSimplify - Removes all diacritics from a string

StringTrim - Left and right trims a string (that is; removes all surrounding whitespace characters such as tabs, spaces and returns).

SubstituteTemplate - Given an object and a template, substitutes all fields in the template. Supports attributes, references, referencesets and constants. (updated in 2.2: Enums are now displayed using their caption instead of key)

Base64Encode - Converts a plain string to a base64 encoded string.

Base64Decode - Converts a base64 encoded string to the plain, original string.

XSSSanitize - Removes all potential dangerous HTML from a string so that it can be safely displayed in a browser. This function should be applied to all HTML which is displayed in the browser and can be entered by (untrusted) users.

RandomStrongPassword - Returns a random strong password containing a specified minimum number of digits, uppercase and special characters.

EncryptString - Decrypts an AES encrypted string. The keylength should exactly be 16 characters (128 bit). (New in 2.4)

DecryptString - Applies AES encryption to the value string using a symmetric key. The keylength should exactly be 16 characters (128 bit). (New in 2.4)

*GenerateHMAC_SHA256_hash - Generates a base64 encoded asymmetric hash using the HMAC_SHA256 hash algorithm.

*GenerateHMAC_SHA256 - Generates a hexadecimal encoded asymmetric hash using the HMAC_SHA256 hash algorithm.

SubstringAfter - Returns the substring of a string after the first occurence of a given separator.

SubstringAfterLast - Returns the substring of a string after the last occurence of a given separator.

SubstringBefore - Returns the substring of a string before the first occurence of a given separator.

SubstringBeforeLast - Returns the substring of a string before the last occurence of a given separator.

Thank you, community.

The contents of this package has been based upon, among others, those forum threads:

mgroeneweg/CommunityCommons