Skip to content

Commit

Permalink
initial release of WDDX module
Browse files Browse the repository at this point in the history
  • Loading branch information
jclausen committed Jun 3, 2024
1 parent 4e077d5 commit de3cb42
Show file tree
Hide file tree
Showing 7 changed files with 656 additions and 521 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ build/**

### Mac OS ###
.DS_Store
grapher

### BOXLANG ###
/libs/
Expand Down
774 changes: 387 additions & 387 deletions .ortus-java-style.xml

Large diffs are not rendered by default.

120 changes: 7 additions & 113 deletions readme.md
Original file line number Diff line number Diff line change
@@ -1,126 +1,20 @@
# ⚡︎ BoxLang Module: WDDX Module

```
|:------------------------------------------------------:|
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------:|
```
The WDDX module provides the bridge between the WDDX exchange format and BoxLang. It involves reading and parsing XML, converting data types, handling errors, and ensuring performance and compatibility. The module enables the integration of legacy systems with new applications.

<blockquote>
Copyright Since 2023 by Ortus Solutions, Corp
<br>
<a href="https://www.boxlang.io">www.boxlang.io</a> |
<a href="https://www.ortussolutions.com">www.ortussolutions.com</a>
</blockquote>
It provides the `wddx` component along with its actions of `bx2wddx`, `wddx2bx`, `bx2js` and `wddx2js`. Note that if the compatibility module is installed in the BoxLang runtime, the usage of `bx` in the action changes to `cfml`.

<p>&nbsp;</p>
_*Important Note:* WDDX is, effectively, no longer supported for new development and its continued use as a data interchange format is is highly discouraged. This module should only be used to maintain compatibility for legacy code and developers should be encouraged to sunset its usage._

This template can be used to create Ortus based BoxLang Modules. To use, just click the `Use this Template` button in the github repository: https://github.com/boxlang-modules/module-template and run the setup task from where you cloned it.

```bash
box task run taskFile=src/build/SetupTemplate
```

The `SetupTemplate` task will ask you for your module name, id and description and configure the template for you! Enjoy!
## Contributed Functions

## Directory Structure
The compat module will contribute the following components globally:

Here is a brief overview of the directory structure:

* `.github/workflows` - These are the github actions to test and build the module via CI
* `build` - This is a temporary non-sourced folder that contains the build assets for the module that gradle produces
* `gradle` - The gradle wrapper and configuration
* `src` - Where your module source code lives
* `.cfformat.json` - A CFFormat using the Ortus Standards
* `.editorconfig` - Smooth consistency between editors
* `.gitattributes` - Git attributes
* `.gitignore` - Basic ignores. Modify as needed.
* `.markdownlint.json` - A linting file for markdown docs
* `.ortus-java-style.xml` - Ortus Java Style for IntelliJ, VScode, Eclipse.
* `box.json` - The box.json for your module used to publish to ForgeBox
* `build.gradle` - The gradle build file for the module
* `changelog.md` - A nice changelog tracking file
* `CONTRIBUTING.md` - A contribution guideline
* `gradlew` - The gradle wrapper
* `gradlew.bat` - The gradle wrapper for windows
* `ModuleConfig.cfc` - Your module's configuration. Modify as needed.
* `readme.md` - Your module's readme. Modify as needed.
* `settings.gradle` - The gradle settings file

Here is a brief overview of the source directory structure:

* `build` - Build scripts and assets
* `main` - The main module source code
* `bx` - The BoxLang source code
* `ModuleConfig.bx` - The BoxLang module configuration
* `bifs` - BoxLang built-in functions
* `components` - BoxLang components
* `config` - BoxLang configuration, schedulers, etc.
* `interceptors` - BoxLang interceptors
* `libs` - Java libraries to use that are NOT managed by gradle
* `models` - BoxLang models
* `java` - Java source code
* `resources` - Resources for the module placed in final jar
* `test`
* `bx` - The BoxLang test code
* `java` - Java test code
* `resources` - Resources for testing
* `libs` - BoxLang binary goes here for now.

## Project Properties

The project name is defined in the `settings.gradle` file. You can change it there.
The project version, BoxLang Version and JDK version is defined in the `build.gradle` file. You can change it there.

## Gradle Tasks

Before you get started, you need to run the `downloadBoxLang` task in order to download the latest BoxLang binary until we publish to Maven.

```bash
gradle downloadBoxLang
```

This will store the binary under `/src/test/resources/libs` for you to use in your tests and compiler. Here are some basic tasks


| Task | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------|
| `build` | The default lifecycle task that triggers the build process, including tasks like `clean`, `assemble`, and others. |
| `clean` | Deletes the `build` folders. It helps ensure a clean build by removing any previously generated artifacts. |
| `compileJava` | Compiles Java source code files located in the `src/main/java` directory |
| `compileTestJava` | Compiles Java test source code files located in the `src/test/java` directory |
| `dependencyUpdates` | Checks for updated versions of all dependencies |
| `downloadBoxLang` | Downloads the latest BoxLang binary for testing |
| `jar` | Packages your project's compiled classes and resources into a JAR file `build/libs` folder |
| `javadoc` | Generates the Javadocs for your project and places them in the `build/docs/javadoc` folder |
| `serviceLoader` | Generates the ServiceLoader file for your project |
| `spotlessApply` | Runs the Spotless plugin to format the code |
| `spotlessCheck` | Runs the Spotless plugin to check the formatting of the code |
| `tasks` | Show all the available tasks in the project |
| `test` | Executes the unit tests in your project and produces the reports in the `build/reports/tests` folder |

## Tests

Please use the `src/test` folder for your unit tests. You can either test using TestBox o JUnit if it's Java.

## Github Actions Automation

The github actions will clone, test, package, deploy your module to ForgeBox and the Ortus S3 accounts for API Docs and Artifacts. So please make sure the following environment variables are set in your repository.

> Please note that most of them are already defined at the org level
* `FORGEBOX_TOKEN` - The Ortus ForgeBox API Token
* `AWS_ACCESS_KEY` - The travis user S3 account
* `AWS_ACCESS_SECRET` - The travis secret S3

> Please contact the admins in the `#infrastructure` channel for these credentials if needed
* wddx ( e.g. `<cfwddx.../>` and `<bx:wddx.../>` depending on the template type, and `wddx...;` in script )


## Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the [community](https://patreon.com/ortussolutions) and [Ortus Solutions, Corp](https://www.ortussolutions.com). Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: [https://patreon.com/ortussolutions](https://patreon.com/ortussolutions)

### THE DAILY BREAD

> "I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12
BoxLang is a professional open-source project and it is completely funded by the [community](https://patreon.com/ortussolutions) and [Ortus Solutions, Corp](https://www.ortussolutions.com). Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visits our patronage page: [https://patreon.com/ortussolutions](https://patreon.com/ortussolutions)
98 changes: 83 additions & 15 deletions src/main/java/ortus/boxlang/modules/wddx/components/WDDX.java
Original file line number Diff line number Diff line change
Expand Up @@ -19,52 +19,120 @@

import java.util.Set;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import ortus.boxlang.modules.wddx.util.WDDXKeys;
import ortus.boxlang.modules.wddx.util.WDDXUtil;
import ortus.boxlang.runtime.BoxRuntime;
import ortus.boxlang.runtime.components.Attribute;
import ortus.boxlang.runtime.components.BoxComponent;
import ortus.boxlang.runtime.components.Component;
import ortus.boxlang.runtime.context.IBoxContext;
import ortus.boxlang.runtime.dynamic.ExpressionInterpreter;
import ortus.boxlang.runtime.dynamic.casters.StringCaster;
import ortus.boxlang.runtime.scopes.Key;
import ortus.boxlang.runtime.types.IStruct;
import ortus.boxlang.runtime.validation.Validator;

@BoxComponent( allowsBody = false )
public class WDDX extends Component {

static Key locationKey = Key.of( "location" );
static Key shoutKey = Key.of( "shout" );
private static final Boolean isCompatMode = BoxRuntime.getInstance().getModuleService().getModuleNames().contains( Key.of( "compat" ) );
private static final String languageTag = isCompatMode ? "cfml" : "bx";

public static final Key toWDDXKey = Key.of( languageTag + "2wddx" );
public static final Key toCFMLKey = Key.of( "wddx2" + languageTag );
public static final Key toJSKey = Key.of( languageTag + "2js" );
public static final Key XtoJSKey = Key.of( "wddx2js" );

static Logger logger = LoggerFactory.getLogger( WDDX.class );

public WDDX() {
super();
declaredAttributes = new Attribute[] {
new Attribute( Key._NAME, "string", Set.of( Validator.REQUIRED ) ),
new Attribute( locationKey, "string", "world", Set.of( Validator.REQUIRED, Validator.valueOneOf( "world", "universe" ) ) ),
new Attribute( shoutKey, "boolean", false, Set.of( Validator.REQUIRED ) ),
new Attribute( Key.action, "string", languageTag + "2wddx",
Set.of( Validator.REQUIRED, Validator.valueOneOf( languageTag + "2wddx", "wddx2" + languageTag, languageTag + "2js", "wddx2js" ) ) ),
new Attribute( Key.input, "any", Set.of( Validator.REQUIRED ) ),
new Attribute( Key.output, "string", Set.of( Validator.REQUIRED ) ),
new Attribute( WDDXKeys.toplevelvariable, "string" ),
new Attribute( WDDXKeys.usetimezoneinfo, "boolean", true ),
// TODO: we warn that these are not supported, for now. Deprecate in a future release
new Attribute( WDDXKeys.validate, "boolean", false ),
new Attribute( WDDXKeys.xmlconform, "boolean", true ),
};
}

/**
* An example component that says hello
* Serializes and de-serializes CFML data structures to the XML-based WDDX format.
*
* Generates JavaScript statements to instantiate JavaScript objects equivalent to the contents of a WDDX packet or some CFML data structures.
*
* This tag cannot have a body.
*
* Note: If the [compatibility module](https://forgebox.io/view/bx-compat) is installed, the use of `bx` in the action attribute changes to `cfml` instead ( e.g. `cfml2wddx` )
*
* @param context The context in which the Component is being invoked
* @param attributes The attributes to the Component
* @param body The body of the Component
* @param executionState The execution state of the Component
*
* @attribute.name The name of the person greeting us.
* @attribute.input The input data to be converted
*
* @attribute.location The location of the person.
* @attribute.output The variable to which the converted data will be assigned
*
* @attribute.shout Whether the person is shouting or not.
* @attribute.action The action to be performed on the input data. One of: bx2wddx, wddx2bx, bx2js, wddx2js
*
* @attribute.toplevelvariable The name of the top-level variable to be used in the generated JavaScript code
*
* @attribute.usetimezoneinfo Whether to use timezone information in the generated JavaScript code
*
* @attribute.validate Whether to validate the input XML
*
* @attribute.xmlconform Whether the WDDX input shoud conform to the WDDX DTD
*/
public BodyResult _invoke( IBoxContext context, IStruct attributes, ComponentBody body, IStruct executionState ) {
String name = attributes.getAsString( Key._NAME );
String location = attributes.getAsString( locationKey );
Boolean shout = attributes.getAsBoolean( shoutKey );
Key actionKey = Key.of( attributes.get( Key.action ) );
Object input = attributes.get( Key.input );
String variable = attributes.getAsString( Key.output );
String toplevelvariable = attributes.getAsString( WDDXKeys.toplevelvariable );
if ( toplevelvariable == null ) {
toplevelvariable = actionKey + "_JS";
}

if ( attributes.getAsBoolean( WDDXKeys.validate ) ) {
logger.warn( "WDDX DTDs are no longer published nor available. Validation cannot not be performed" );
}

if ( !attributes.getAsBoolean( WDDXKeys.xmlconform ) ) {
logger.warn( "The WDDX component only allows valid XML. All input must be valid xml. The argument `xmlConform` will be ignored." );
}

StringBuilder sb = new StringBuilder();
String greeting = sb.append( "Hello, " ).append( location ).append( " - from " ).append( name ).append( "." ).toString();
context.writeToBuffer( shout ? greeting.toUpperCase() : greeting );
if ( actionKey.equals( toWDDXKey ) ) {
ExpressionInterpreter.setVariable(
context,
variable,
WDDXUtil.serialize( input )
);
} else if ( actionKey.equals( toCFMLKey ) ) {
ExpressionInterpreter.setVariable(
context,
variable,
WDDXUtil.parse( StringCaster.cast( input ) )
);
} else if ( actionKey.equals( toJSKey ) ) {
ExpressionInterpreter.setVariable(
context,
variable,
WDDXUtil.serializeToJavascript( input, toplevelvariable )
);
} else if ( actionKey.equals( XtoJSKey ) ) {
ExpressionInterpreter.setVariable(
context,
variable,
WDDXUtil.translateToJavascript( StringCaster.cast( input ), toplevelvariable )
);
}

return DEFAULT_RETURN;
}
Expand Down
36 changes: 36 additions & 0 deletions src/main/java/ortus/boxlang/modules/wddx/util/WDDXKeys.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/**
* [BoxLang]
*
* Copyright [2023] [Ortus Solutions, Corp]
*
* 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.
*/
package ortus.boxlang.modules.wddx.util;

import ortus.boxlang.runtime.scopes.Key;

/**
* Represents a case-insenstive key, while retaining the original case too.
* Implements the Serializable interface in case duplication is requested within
* a native HashMap or ArrayList
*/
public class WDDXKeys {

public static final Key _MODULE_NAME = Key.of( "wddx" );

public static final Key toplevelvariable = Key.of( "toplevelvariable" );
public static final Key usetimezoneinfo = Key.of( "usetimezoneinfo" );
public static final Key validate = Key.of( "validate" );
public static final Key xmlconform = Key.of( "xmlconform" );

}
Loading

0 comments on commit de3cb42

Please sign in to comment.