Implementing Custom Windchill Adapter Webjects
The Windchill adapter is an embedded component of the Windchill method server. The Windchill adapter receives requests to execute Info*Engine tasks and webjects. Webjects can perform various functions, including the following:
• Comparing, combining, and sorting groups of business objects
• Searching for information matching a specified criteria
• Performing information manipulation actions such as creating, copying, and updating.
Query and action webjects are specialized for each adapter that is used to access and alter data in an information system. These and other categories of webjects are further described in the section
Info*Engine User’s Guide, which also describes how to create custom webjects.
You can provide custom query and action webjects for use with the Windchill adapter.
Setting Up a New Custom Webject Delegate
Each webject delegate must have a unique name. The Windchill adapter uses this name along with any class information provided by the webject to locate a class implementing your webject delegate. All type-aware webject delegates must implement the com.ptc.core.adapter.server.impl.TypeAwareWebjectDelegate interface, which provides the following method:
com.infoengine.object.factory.Task invoke(com.infoengine.object.factory.Task task)
This invoke() method performs all the work of each concrete webject delegate class implementing the TypeAwareWebjectDelegate interface.
The following is the basic outline of operation for an implementation of the invoke() method:
1. Extract the webject object from the incoming task object.
2. Perform operations based on the parameters specified in the webject object.
3. Store the resulting data in element objects within a group object.
4. Return a new task object containing the group object output data.
For more information on the com.infoengine.object.factory.Task class, refer to its javadoc.
Locating the Custom Webject Class
Webject delegates are registered with the Windchill adapter by entries in wt.adapter.delegates.properties. The Windchill adapter invokes webject delegates based on the webject name and the class or type of the target object.
For example, the following line in wt.adapter.delegates.properties registers the CheckinObjectsWebjectDelegate with the Windchill adapter:
CHECKINOBJECTS.WCTYPE|
java.lang.Object=com.ptc.core.adapter.server.impl.CheckinObjectsWebjectDelegate
The class (or Windchill subtype) of the target object is taken from the TYPE parameter of the incoming webject. Hyphens included in the webject name by the caller are ignored, and the webject lookup is also case-insensitive.
This performs the following functions:
1. The adapter receives a webject request for CHECKINOBJECTS for a target object with the java.lang.Object class.
2. The webject delegate com.ptc.core.adapter.server.impl.CheckinObjectsWebjectDelegate is instantiated.
3. Its invoke() method is then executed.
Writing a New Webject Delegate
Most Windchill adapter webjects reside in the com.ptc.core.adapter.server.impl package. For simplicity, the Windchill adapter webjects are not modeled. Most webject subclasses have common parent classes that based on the type of adapter webject.
• OBJ webjects typically extend com.ptc.core.adapter.server.impl.ObjectWebject
• ACT webjects extend com.ptc.core.adapter.server.impl.ActionWebject
• Both ObjectWebject and ActionWebject extend com.ptc.core.adapter.server.impl.AbstractWebject.
Each class provides useful convenience methods and parameter support applicable to the type of webject being written. Subclasses of any of these also inherit the TypeAwareWebjectDelegate interface. Subclasses need only implement the invoke() method.
For a detailed list of methods available to each, refer to the javadoc for com.ptc.core.adapter.server.impl.
Windchill adapter webjects drive parameter gathering and validation by use of core Info*Engine Java annotations. This ensures that all webjects process input parameters as consistently as possible, report consistent error messages, and do not need to duplicate source code for routine tasks.
If you make use of existing super classes (ObjectWebject, ActionWebject, or AbstractWebject), each class defines the parameters that it gathers and uses, so subclasses need only define the parameters that they specifically use that are not already being gathered by a parent class. Webject parameter validation can then perform all basic validation of things such as the following:
• Existence of required parameters
• Existence of interdependent parameters
• Mutually exclusive parameters are not specified together
• Parameters conform to the data types they are defined to contain
This leaves only basic parameter validation to the webject implementation itself.
If you decide to extend an existing base class, then the first thing your class should do in its invoke method implementation is to call the parent class' preset method. This validates parameters and gathers common parameters.
If you do not decide to extend a common base class, then you must either force parameter validation yourself (if using annotations) or manually gather parameters from the webject.
The annotations that are used for parameter validation are com.infoengine.object.factory.WebjectDef and com.infoengine.object.factory.ParameterDef.. For more information, see the examples in the following topics.