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.
ICMPagedResult<T> An ICMPagedResult represents a collection of query results in a page-based structure.
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 WebLogic Portal Content Management.

This includes the ability to iterate over results, check the size of the results, apply sorting and filtering on both the initial query and 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:

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: 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: 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 WLP 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: The following custom sorting and filtering capabilities are available: 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...



Copyright © 2000, 2008, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.