API’s Available for Custom Filter Applications
Server side API available to navigate the Design Context Structure
public interface ContextBuilderInterface {
public Collection<CBStructureNode>
getChildrenFromCache(String collectorCacheID,
Collection<String> seeds, HttpServletRequest request) throws
InvalidCollectorCacheException, InvalidCollectorSeedException,
CollectionException;
}
The inputs to the API are:
• Collector Cache ID (String): This is the parameter passed to the custom filter application in the URL when the custom filter application is launched (CB_CCID parameter)
• Seeds/Collection of components to traverse (Collection of Strings) : For the first call, this should contain the id passed to the custom filter application in the URL when the custom filter application is launched (CB_SEEDID), for subsequent calls, the collection should contain the ids of the components returned from previous call that need to be traversed further to get to the CAD modules – when all CAD modules are retrieved, then this API should not be called anymore.
• Request : As the customization may execute within the context of a separate web app, the HTTP request object needs to be passed in as input to the Context Builder API such that Windchill picks up the authenticated user, the user locale, HTTP session specific data, etc to establish the appropriate context for the execution of this API. If the request object is null, then it is assumed that no initialization of context is required.
The output of this API is:
• A collection of CBStructureNode : This object would contain a child component id (string), the child Persistable object, a link id (string), the link Persistable object (between parent and child), the parent id (string), a string representing the path of that component in the structure and its inclusion status
For each combination of child component id + path we would have a CBStructureNode object
Exceptions may be thrown in the following situations:
• InvalidCollectorCacheException - collector cache id is no longer valid
• InvalidCollectorSeedException - seed object(s) passed are invalid (we cannot refresh them)
• CollectionException - collection exception
These exceptions are extensions of WTException; therefore in any error case mentioned above localized error messages will be returned in them.
The caller of this API should also be prepared to deal with runtime exceptions (db unavailable, etc).
This API will not return items that are filtered by Expansion Criteria filters (those items are not displayed in the context builder tree and would not be available to this API).
This API will return the link and child identifiers and Persistable objects. It is up to the invoker API to then use other services to acquire additional information about the object using other APIs (info engine or other Windchill supported APIs) if not available in the Persistable objects (for example, reusable attributes would not be available from the Persistable objects). This API will not return any information about the level of representation selected for each item in the structure.
The identifier returned in the CBStructureNode object will be of the form: OR:<object class>:<number>
Server Side API Available to Update the Context Builder Cache
public interface ContextBuilderInterface {
public String addRulesToCache(String collectorCacheID, String seedId,
List<CBPath> nodesToUpdate, HttpServletRequest request) throws WTException;
}
The following are the inputs to this API:
• Collector Cache ID – This is the parameter passed to the custom filter application in the URL when the custom filter application is launched (CB_CCID parameter)
• Seed ID – This is the parameter passed to the custom filter application in the URL when the custom filter application is launched (CB_SEEDID parameter)
• List of CBPath items for which we should add new inclusion/exclusion rules – this List should include the CBPath items that have been modified by user – for items not modified, they should not be passed in. The reason why CBPath’s are passed to this API instead of CBStructrueNodes is because, for creation of rules, only the information in CBPath’s is required. To create an instance of a CBPath using the path identifier (that was given to the custom filter application in the CBStructureNode objects) and an inclusion value, please use the CBPathFactory.
Please note that instead of a Collection, a List is passed to this API – if for some reason, the order of inclusions for paths is important, then it is up to the invoker of the API to pass the CBPaths in appropriate order for creation – the order in which rules are created can potentially modify the end result of inclusions in the context.
In addition, it is up to the application to decide how to handle multiple paths to same component (if all should be set to same inclusion status or not).
• Request – As the customization may execute within the context of a separate web app, the HTTP request object needs to be passed in as input to the Context Builder API such that Windchill picks up the authenticated user, the user locale, HTTP session specific data, etc to establish the appropriate context for the execution of this API. If the request object is null, then it is assumed that no initialization of context is required.
As output, this API will:
• On failure, an exception will be returned – the exception will have a localized message with information about the failure.
• On success, this API will provide as output a string that has a token that is to be used by client Context Builder to refresh the screen after the custom filter UI is dismissed (the tree, visualization and rules panel would be updated accordingly).
This API will add rules for the paths passed in (according to the inclusion state passed in) at the bottom of the rules list of the associated context. For CAR’s, the representation will be set based on the preference value in the system.
Client side API to Hand Over Control to Context Builder on Success of Custom Filtering
On success of the custom filter application, the custom filter application should hand over control to the context builder and should request it to refresh itself.
When called to refresh, the custom builder will close the custom filter application and should go to server (by using token passed by API defined in previous section) to get the data to be refreshed in the Context Builder application.
After refresh is done, the modal mode should be dismissed in the Context Builder application and should be fully functional again for the user.
The following API is available to the custom filter application to hand over control to the context builder application (this is a JavaScript API)
opener.CB.refreshContextBuilderForCustomFilter(token);
Where the input to this API is:
• Token – This is the string returned by the addRulesToCache API defined in previous section – this is a required input and the API will fail if no token is passed.
This API does not produce any output (void call).
Client side API to Cancel Custom Filter
When the custom filter window is closed, a JavaScript API should be called on the opener window (the Context Builder window) to reset the modal mode.
This API should be invoked when a cancel button is pressed on the custom filter window or when the custom filter window is “unloaded” (closed by pressing the “X” button on the browser window).
The API should be called in the following way:
opener.CB.closeCustomFilterWindow();
This API does not produce any output (void call).