ATG Platform REST Web Services includes functionality that filters properties from output. You could use this functionality to:
Mark a certain property in a Nucleus component or repository item as hidden or not writable.
Configure the system to override the default functionality of outputting all items and instead output only the items defined in the filtering configuration file.
Add your own custom properties for components or repository items and specify from where to get their values.
An extension of the property filtering feature, called property aliasing, allows you to create virtual components with properties that assemble values from a variety of sources.
The filtering configuration file is located at /atg/rest/filtering/filteringConfiguration.xml
in the config path. To customize it you will create that file in your own module and the server’s XML combination functionality will combine all the filteringConfiguration.xml
files.
The following sample makes one property hidden and another writable in a Nucleus component and a repository item:
property1
andrepProperty1
are both hidden and will not be returned in the output whenever the Nucleus component or that specific property is requested.property2
andrepProperty2
cannot be changed by a REST request. (Note that the writable flag affects only REST requests.)
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> </item-descriptor> </component> </rest-filtering>
The default-include
attribute tells the server that it should return only the values specified inside this component tag and ignore all other properties of the Nucleus component or repository item.
The following sample adds additional properties which do not exist in the Nucleus component or repository item. The sample also configures where the values for these “virtual” properties come from.
The property called
virtual1
does not exist in the/some/Component
bean. Its value, specified by thetarget
attribute, is the value ofproperty2
in the same object.Similarly, the
repVirtual1
property returns the value ofrepProperty2
as its value.The
target
attribute also allows for subproperties to be specified, as the sample demonstrates for thevirtual2
andrepVirtual2
properties. Note that the dot notation can be more than one level deep.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> </item-descriptor> </component> </rest-filtering>
The next sample extends the previous one by adding a component attribute to the property tag and using that in combination with the target tag. This demonstrates how the value of a property can come from another Nucleus component. (Note that the component attribute can only reference a Nucleus component.) Dot notation can be used in the target attribute when the component attribute is used.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty"/> </item-descriptor> </component> </rest-filtering>
Finally, if you need to write custom code to specify your value, then you must use the property-customizer
attribute, as shown in the following sample.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> <property name="virtual4" property-customizer="some.class.Here"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty"/> <property name="repVirtual4" property-customizer="some.class.Here"/> </item-descriptor> </component> </rest-filtering>
When using the property-customizer
attribute, the value should be the name of a class which implements the atg.rest.filtering.RestPropertyCustomizer
interface, shown below.
public Object getPropertyValue(String pPropertyName, Object pResource);
public void setPropertyValue(String pPropertyName, Object pValue, Object pResource);