Skip to main content

Struts API

org.normalizedsystems.beam:struts-api-beam::1.4.0

The Struts API is a control layerLayerLogical separation of functionality within a single system/application, focused on code organization. for NS JEE applicationsApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. built on Apache Struts 2. It exposes a JSON API for all data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. in the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution., covering CRUD operations, findersFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement., projectionsProjectionA tailored subset of fields on a DataElement designed to encapsulate data for a specific technical or functional view., tasks and data commandsData Command (DataCommand). [Deprecated] A legacy mechanism used for data input and custom action execution on DataElements, replaced by DataOperations.. The Struts API is meant to serve the Knockout frontend.

The Struts API is included in the minimal-jee-beam. For modular setups, such as one based on the jee-backend-beam, it is available separately as the struts-api-beam.

tip

The Struts API is still maintained, but it no longer receives new features. For new projects, use the Standard API.

Endpoints​

Every data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. gets a set of JSON endpoints. The endpoints are grouped per component and follow the URL pattern:

/<application>/<component>/<dataElement>-<action>-json

For example, the details of the data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. Person in the component crm are available at /<application>/crm/person-detail-json. Parameters are passed as request parameters or in a JSON request body. The instance identifier is passed as <dataElement>Oid, for example personOid.

ActionDescriptionMain parameters
detailReturns the details projectionProjectionA tailored subset of fields on a DataElement designed to encapsulate data for a specific technical or functional view. of one instance.<dataElement>Oid
searchExecutes a finder and returns a page of results.searchMethod, details.<field>, page, rowsPerPage, sortFields, fetchAll, projection
saveDetails, confirmCreates a new instance, or updates an existing instance when <dataElement>Oid is given.<dataElement>Oid, <dataElement>.<field>
deleteDeletes one instance.<dataElement>Oid
modifyUpdates an instance with a projectionProjectionA tailored subset of fields on a DataElement designed to encapsulate data for a specific technical or functional view.. Only available with the option cruds.modifyWithProjection.projection, details.<field>
performPerforms a task on an instance, or sets the status of a task.<dataElement>Oid, taskName, paramString, targetStatus
getProjectionReturns one instance in the requested projection.id, projection
perform-commandPerforms a data command and returns a commandResult.commandName, command.<field>
uploadImports a file. Only available for data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. with the tag #io.import.type, file
downloadExports a file. Only available for data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. with the tag #io.export.type

In addition to the data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. endpoints, the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. exposes some general endpoints in the root namespace:

ActionDescription
translate-jsonTranslates text.
menu-jsonReturns the menu for an applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. and role.
findersForDataElement-jsonReturns all findersFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement. for a data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept..
getComponentMetaData-jsonReturns the metadata of a component.
getDataElementMetaData-jsonReturns the metadata of a data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept..
getApplicationProperties-jsonReturns the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. properties.
request-nonce-jsonReturns a nonce for CSRF protection.

Security​

When the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. contains the account base component, the Struts API uses it for authentication and authorization. Interceptors on all endpoints check the user session and the access rights of the user.

The implementations for authentication and authorization can be changed through the account.ns.properties file. See Customizing authorization.

Option
struts.security.custom ApplicationApplicationInstance

Disables the security integration with the account component, so that you can provide a custom security implementation.

<options>
<struts.security.custom/>
</options>
Option
struts.security.csrfProtection ApplicationApplicationInstance

Adds protection against cross-site request forgery to all endpoints that change data. The client requests a nonce from request-nonce-json and sends it in the request parameter. Each nonce can only be used once and stays valid for 30 minutes.

<options>
<struts.security.csrfProtection/>
</options>
Option
struts.security.enforceHttpMethod ApplicationApplicationInstance

Enforces the correct HTTP method on each request. Endpoints that retrieve data only accept GET. Endpoints that change data only accept POST. Other methods return the status 405 Method Not Allowed.

<options>
<struts.security.enforceHttpMethod/>
</options>
Option
experimental.struts.security.enforceAnnotatedParameters ApplicationApplicationInstance

Enforces the use of the @StrutsParameter annotation in Struts actions. Struts then only injects request parameters into setters with this annotation, or in objects returned by getters with this annotation. Add the annotation to custom actions as well.

<options>
<experimental.struts.security.enforceAnnotatedParameters/>
</options>
Option
struts.unauthorized ApplicationApplicationInstance

Sets what happens when an unauthorized user calls an endpoint. With redirect, the default, the user is redirected to the login page. With error-page, a dedicated error page is shown.

<options>
<struts.unauthorized>redirect</struts.unauthorized>
</options>
<options>
<struts.unauthorized>error-page</struts.unauthorized>
</options>
Option
struts.unauthorized.json ApplicationApplicationInstance

Returns an HTTP status code for unauthorized JSON requests. The value has the format status <statusCode>.

<options>
<struts.unauthorized.json>status 401</struts.unauthorized.json>
</options>

Authentication methods​

The account component supports two authentication methods for the Struts API:

Configuration and customization​

JSON payload limits​

The NSXJsonInterceptor reads the JSON request body. By default, it does not limit the size of the payload. You can set limits with the following Struts constants:

ConstantLimits
nsx.struts.json.maxElementsThe number of elements.
nsx.struts.json.maxDepthThe nesting depth.
nsx.struts.json.maxLengthThe total length of the payload.
nsx.struts.json.maxStringLengthThe length of a string value.
nsx.struts.json.maxKeyLengthThe length of a key.

Add the constants to the custom-constants anchorAnchorA marker within generated source code reserved for adding custom logic during re-expansion. of struts-header.xml:

war/src/main/resources/struts-header.xml
<!-- anchor:custom-constants:start -->
<constant name="nsx.struts.json.maxDepth" value="20"/>
<constant name="nsx.struts.json.maxStringLength" value="100000"/>
<!-- anchor:custom-constants:end -->
info

The JSON payload limits are available as of minimal-jee-beam 2.5.0 and struts-api-beam 1.3.0.

Custom JSON serialization​

The Struts API serializes responses with the NSXJSONWriter class, which is configured as struts.json.writer. To customize the serialization of objects, add custom code in the struts-json-writer-process custom anchorAnchorA marker within generated source code reserved for adding custom logic during re-expansion. of NSXJSONWriter.java.

caution

Before minimal-jee-beam 2.5.0 and struts-api-beam 1.3.0, a custom struts.json.writer could be configured. Move such customizations to the NSXJSONWriter class.