The filtering configuration file is located at /atg/rest/filtering/filteringConfiguration.xml
in your Oracle ATG Web Commerce platform server’s configuration path. To customize it, create that file in your own module and the server’s XML combination functionality will combine all the filteringConfiguration.xml
files.
Include component
elements in the file to configure the filtering applied to requests for Nucleus components and repositories. Set the name
attribute of the component
element to a Nucleus component path, a repository path, or a fully qualified Java class or interface name. If you enter a Java class or interface name, the filtering behavior will apply to objects that are subclasses or implementations of it. Filters for Nucleus component paths override filters for Java classes and implementations. Only one filter can apply to a request for an object.
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);
You can also set the property-customizer
attribute to a Nucleus component path. The component must be an instance of a class that implements the atg.rest.filtering.RestPropertyCustomizer
interface.
Specifying the Filter Depth
You can control the nested level at which a filter will be applied. The number of nested levels at which the filter is applied is the filter depth. A filter depth of zero indicates that the filter should apply only to the immediate properties of the component the filter is configured for. A filter depth of one indicates that the filter should apply to the first nested level of properties.
To set the filter depth for a repository, add the depth
attribute to the item-descriptor
element. For example:
<component name="/atg/userprofiling/ProfileAdapterRepository" default-include="false"> <item-descriptor name="user" depth="1"> <property name="wishlist" hidden="false"/> <property name="creditCards" hidden="false"/> </item-descriptor> </component>
To set the filter depth for a non-repository component, add the depth
attribute to the component
element. For example:
<component name="/atg/resttest/BeanTest" depth="0" default-include="false"> <property name="repository" hidden="false"/> </component>