Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright © 2006 BEA Systems, Inc. All Rights Reserved
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package com.bea.content.paging

Package com.bea.content.paging for query result collection types

See
Description

Interface Summary
ContentListKeys | Common context keys which can be used across CMPagedResult and IPagedList result collection types.
IFilterablePagedList<T> | An IPagedList which can be filtered.
IObjectFilter | Interface which allows custom filtering to use the entire object state, for specified Java types.
IObjectSorter | Interface which allows custom sorting to use the entire object state, for specified Java types.
IPagedList<T> | An IPagedList represents a collection of query results.
IPagedListIterator<T> | A bi-directional iterator for traversing query results in a read-only manner.
IPropertyFilter | Interface which allows custom property filtering, for specified Java property container types and specified JavaBean properties.
IPropertyProvider | Interface to expose one or more 'extended' properties, for specified Java property container types.
IPropertySorter | Interface which allows custom property sorting, for specified Java property container classes and specified JavaBean properties.
IPropertyTypeFilter | Interface which allows custom property type filtering, for specified Java property container types.
IPropertyTypeSorter | Interface which allows custom property type sorting, for specified Java property container types.
ISortableFilterablePagedList<T> | An IPagedList which can be both sorted and filtered.
ISortablePagedList<T> | An IPagedList which can be sorted.

Class Summary
CMPagedResultFactory<T> | supports creating an ICMPagedResult from a PagedList
FilterCriteria | query filter criteria.
PagedListFactory<T> | supports creating a ISortableFilterablePagedList from a List
SortCriteria | query sort criteria

## Package com.bea.content.paging Description

### Package com.bea.content.paging for query result collection types

This package and sub-packages work together to provide query result collection support for BEA Portal Content Management.

This includes the ability to iterate over results, check the size of the results, apply sorting and filtering during both the initial query and to query results, determine which properties can be sorted and filtered, extend/override sorting and filtering capabilities, and various other operations.

#### Result Collection Types

There are two primary query result collection types:

- IPagedList and its subtypes ISortablePagedList, IFilterablePagedList, and ISortableFilterablePagedList can be used examine and iterate over query results, and work similar to the Java interfaces List and Iterator. Data may be loaded on-demand as iteration occurs. Data loading boundaries are hidden from the client. The CM Federated APIs generally return IPagedList collections.

- CMPagedResult can be used to examine and iterate over query results on a page basis, and is an implementation of com.bea.p13n.pagination.PagedResult. This type supports the concept of 'pages' with a configured size, which items are retrieved onto. One can move to previous/next pages, retrieve all the query results for a specific page, etc. A CMPagedResult can be created from an IPagedList.

#### Important Notes

Two important notes regarding the interfaces and classes in this package:

1. First, the query result collection types do not support changing the results via the collection. For example, suppose you do a search and get back 10 Nodes in the collection. If you want to remove a node so it will no longer appear if the query is re-issued, you need to call the CM APIs to remove a node, rather than directly removing the node from the collection type. Similarily, after you change a node, you need to call the CM APIs to save the node. The query result collections do not persist their data as changes are made.

2. Second, the query result collections may not reflect the current data in the content system. So when you call CM APIs which change the content system data, be aware that the changes may not be reflected in the collection types. You may want to re-issue a query to obtain another collection object if you want to determine the current status.

### Sorting and Filtering

Both collection types support sorting and filtering, and this can be done either during the initial query, or applied to the query results. Sorting and filtering can also be used in conjunction. The collection types currently support single-criteria sorting and filtering.

#### Properties

The sorting and filtering features are based on the JavaBean properties exposed by the associated type, and the associated property types. For example, the com.bea.content.Node type has both a String getName() method, and an ObjectClass getObjectClass() method. Therefore, it has a 'name' property with a String property type, and an 'objectClass' property with an ObjectClass property type.

##### Standard sorting capabilities

All properties which have property types that implement Comparable can be sorted. Note that since the Comparable interface cannot handle null values, standard sorting capabilities do not support null properties. If desired, this can be added with a custom property sorter.

Continuing the previous example, the Node 'name' property, which has property type String, can be sorted, since String implements Comparable.

By comparison, the Node 'objectClass' property, which has property type ObjectClass, does not have automatic sorting capability, since ObjectClass does not implement Comparable. Note that this support can be added by adding a custom IPropertyTypeSorter.

##### Standard filtering capabilities

The following property types support filtering:

- Boolean / boolean
- Byte / byte
- Character / char
- Double / double
- Float / float
- Integer / int
- Long / long
- Short / short
- String

Just as with the standard sorting capabilities, the standard filter capabilities do not support null properties. If desired, this can be added with a custom property filter. Continuing the previous example, the Node 'name' property, which has property type String, can be filtered upon, since String is in the list of supported filter property types.

By comparison, the Node 'objectClass' property, which has property type ObjectClass, does not have automatic filtering capability. Note that this support can be added by adding a custom IPropertyTypeFilter.

##### Determining sortable/filterable properties

The performance and scalability of sorting and filtering depend upon several factors, including whether the back-end repository supports sorting and filtering during queries. Therefore, sorting and filtering properties can be divided into two groups:

- 'native' properties: these are sorting and filtering properties which the back-end repository supports during during query processing. Native properties are expected to perform efficiently / scale well for large datasets.
- 'non-native' properties: these are sorting and filtering properties which the back-end repository does not support during query processing. These properties may not perform efficiently / scale well for large datasets. Custom sorting and filtering fall into this category.

To determine the full set of sortable and filterable properties (both native and non-native), you can call the getAllSortableProperties / getAllFilterableProperties() methods. The 'native' properties can be determined by calling the getNativeSortableProperties() / getNativeFilterableProperties() methods. See also the documentation for the com.bea.content.paging.ContentListKeys interface.

Some filter methods do not make sense for given property types. If a property is a string, then the GREATER_THAN filter method does not make sense. Additionally, filter and sort values are repository specific. For example, filtering on date properties within the BEA Repository requires that the value be passed in as the number of seconds since 1/1/1970. Consult your repository and or SPI documentation for more information.

#### Criteria

The sort and filter criteria are built upon the concepts in com.bea.p13n.pagination.SortablePagedResult and com.bea.p13n.pagination.FilterablePagedResult, and are reflected in the classes com.bea.content.paging.SortCriteria and com.bea.content.paging.FilterCriteria.

Initial sorting and filtering is done by specifying the SortCriteria and/or FilterCriteria in the ContentContext before calling the query method. Use the ContextKeys listed in com.bea.content.paging.ContentListKeys to specify the criteria.

Resorting and refiltering a query result collection is done by calling the PagedList and/or CMPagedResult reSort and reFilter methods.

For example, you could do something like this:

        ContentContext contentContext= new ContentContext(request);

        // initial sorting ascending by node name
        List scList= new ArrayList();
        scList.add( new SortCriteria( SortOrder.ASCENDING, "name" ) );
        contentContext.setParameter( ContentListKeys.SORT_CRITERIA_KEY, scList );

        ISortablePagedList pagedList= nodeManager.getNodes( contentContext, PathHelper.SEPARATOR + repositoryName);
        // use pagedList...

        // resort descending by last modified date
        pagedList.reSort( SortOrder.DESCENDING, "modifiedDate", null );

### Custom Sorting and Filtering

If the standard sorting and filtering capabilities do not meet your needs, you can add various sorting and filtering capabilities with custom sorters and filters.

You can also use custom sorters and filterers to override the sorting/filtering behavior.

#### Important Notes re: Custom Sorting and Filtering:

Custom sorting and filtering capabilities do not participate in native queries. Therefore, properties using custom sorting/filtering capabilities are automatically non-native properties. When custom sorting/filtering are used with queries, and the sort/filter criteria use the custom sorting/filtering, the query results may need to be loaded into memory, which may reduce the performance and scalability.

Therefore, if you are expecting to retrieve a large number of query results of a type, such as com.bea.content.Node, then custom sorting and filtering may not be a good option. If you are expecting to issue a narrow query, and retrieve a small number of query results of a type, then custom sorting and filtering may work well.

#### Custom Sorting and Filtering Capabilities

The terminology related to custom sorting and filtering can be a little confusing. Here are a few terms to keep in mind:

- property container type: This is a class which contains the JavaBean properties. For example, the com.bea.content.Node class contains the properties 'name' and 'objectClass', since it has methods getName() and getObjectClass().
- property type: This is the type of a specific JavaBean property. For example, the com.bea.content.Node class contains a 'name' property of type String, since it has a String getName() method.

The following custom sorting and filtering capabilities are available:

- `IPropertyProvider`: This interface allows additional properties to be exposed for a given type, such as adding a 'objectClassName' property for com.bea.content.Node. The extended properties can be used when sorting and filtering. The property provider code can access the entire object, for example, com.bea.content.Node.
- `IPropertyTypeSorter`/`IPropertyTypeFilter`: These interfaces allow sorting/filtering support to be added/overridden for individual property types, such as String. The sorting/filtering code has access to only the property value.
- `IPropertySorter`/`IPropertyFilter`: These interfaces allow sorting/filtering support to be added/overridden for individual properties, such as the com.bea.content.Node 'name' property. The sorting/filtering code has access to only the property value.
- `IObjectSorter`/`IObjectFilter`: These interfaces allow sorting/filtering to be added for entire objects, rather than individual properties. The sorting/filtering code can access the entire object, for example, com.bea.content.Node.

Please see each interface's javadoc for the full details.

#### Implementing Custom Sorting and Filtering

In general, once you determine which interface is the best match for the capability you wish to provide, you need to specify which container types you want the support to be added for.

This is done by implementing the Set ITypeSupport.getSupportedTypes( ContentContext ) method on the interface. For example, suppose you want to add support for filtering properties with property type Calendar, so you implement the IPropertyTypeFilter interface.

The implementation of the getSupportedTypes() method defines which container types you want the custom support to be applied to. You can either provide a Set of specific container types, such as com.bea.content.ObjectClass and com.bea.content.Node, or return null, in which case the support will be added across all container types.

In general, the set of available custom sort/filter implementations are considered together when sorting/filtering is performed. For example, one IPropertyTypeFilter implementation might provide the ability to filter Calendar property types, but only implement the EQUALS and NOT_EQUALS filter methods. Another implementation might provide the GREATER_THAN and LESS_THAN filter methods for Calendar property types. All four filter methods would be available for filtering a Calendar property.

#### Custom Sorting and Filtering Precedence Rules:

Precedence rules control the order in which custom sorting and filtering implementations are used, and to allow anything to be overridden. Precedence rules generally only apply when sorting on properties (as compared to object sorters, which sort on objects).

The precedence rules are ordered as follows:

1. IPropertySorter / IPropertyFilter capabilities to either add or override support for specific properties on specific container types.
2. IPropertyTypeSorter / IPropertyTypeFilter capabilities to either add or override support for property types.
3. standard sorting / filtering capabilities for both standard and extended properties (Properties available via an IPropertyProvider implementation)

For example, the com.bea.content.Node 'name' property of property type String has standard sorting support, since it is a String, which is Comparable. One could provide an IPropertyTypeSorter to redefine all String property type sorting to ignore case. In addition, an IPropertySorter could be provided to sort the 'name' property of Node. If both were provided, then sorting on the Node 'name' property would use the IPropertySorter implementation, since it is highest on the precedence order. If another String property existed on Node, then the IPropertyTypeSorter implementation would be used.

#### Using Custom Sorting and Filtering

Once you have implemented a custom sorting or filtering interface, you need to register the implementation so that you can use it when sorting and filtering. This is done by creating an instance of the implementation class, and placing it in the ContentContext with a specific key.

In general, a list of implementations of a given type (such as IPropertySorter) are placed in the ContentContext with a given context key, and the system will scan through this list as needed when sorting and filtering, to find the implementations which apply.

For example:

        // register a property sorter that can sort the Node 'name' property
        // ignoring case
        ContentContext context= new ContentContext(request);

        IPropertySorter customPropSorter= new NodeCustomNamePropertySorter();
        List propertySorters= new ArrayList();
        propertySorters.add( customPropSorter );
        context.setParameter( IPropertySorter.PROPERTY_SORTER_KEY, propertySorters );

        // initial sorting descending by node name
        List scList= new ArrayList();
        scList.add( new SortCriteria( SortOrder.DESCENDING, "name" ) );
        contentContext.setParameter( ContentListKeys.SORT_CRITERIA_KEY, scList );

        ISortablePagedList pagedList= nodeManager.getNodes( contentContext, PathHelper.SEPARATOR + repositoryName);
        // use pagedList...

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Copyright © 2006 BEA Systems, Inc. All Rights Reserved