Package wt.federation

The federation service (wt.federation package) provides functionality to create and manage proxy objects of remote systems and perform utility functions supporting the federation system.

See:
Description

Interface Summary

Federated	Supported API: true Extendable: false
FederatedService	Defines the essential interface for all classes implementing Federated services that provide access to non-local objects.
FederationService	FederationService provides client invokable methods to federation services.
FederationServiceSvr	FederationServiceSvr provides methods to federation services that can only be invoked from classes running on the server.
QuerySpecTranslator	This interface defines the attributes and methods required of a class that implements translation of wt.query.QuerySpec objects to strings representing search filters in foreign systems, especially systems accessed via Info*Engine.

Class Summary

DirectoryAttributeHolder	Supported API: true Extendable: false
DirectoryTranslationTable	Use the newDirectoryTranslationTable static factory method(s), not the DirectoryTranslationTable constructor, to construct instances of this class.
FederatedDirectoryService	This class implements a Federated interface to directory services such as LDAP-accessible directory services.
FederatedHttpBodyPart	Defines and manages MIME body parts contained in HTTP request and response messages.
FederatedHttpConnection	Creates HTTP connections to remote systems, sends requests, and returns the responses received.
FederatedHttpInputStream	Supported API: true Extendable: false
FederatedHttpMessage	Represents an HTTP protocol request or response message.
FederatedHttpMultipart	Represents a MIME multipart object contained in an HTTP request or response message.
FederatedHttpResponse	Parses and provides access to the elements of an HTTP protocol response.
FederatedInfoEngineService	This class implements FederatedService objects that use Info*Engine to access remote systems and data sources.
FederationHelper	FederationHelper provides client invokable methods to federation services.
FederationServerHelper	FederationServerHelper provides server invokable methods to federation services.
InfoEngineTranslationTable	Generate a unique identifier for a remote object given a key and a set of name/value substitutions.
ProxyDocument	Use the newProxyDocument static factory method(s), not the ProxyDocument constructor, to construct instances of this class.
ProxyDocumentMaster	Use the newProxyDocumentMaster static factory method(s), not the ProxyDocumentMaster constructor, to construct instances of this class.
ProxyGroup	Proxy group of users.
ProxyPartMaster	Use the newProxyPartMaster static factory method(s), not the ProxyPartMaster constructor, to construct instances of this class.
ProxyURLData	Use the newProxyURLData static factory method(s), not the ProxyURLData constructor, to construct instances of this class.
ProxyUser	Use the newProxyUser static factory method(s), not the ProxyUser constructor, to construct instances of this class.
Redirector	This class provides the HTTP interface for Federated RMI.
ServiceIdentifier	Use the newServiceIdentifier static factory method(s), not the ServiceIdentifier constructor, to construct instances of this class.
StandardFederationService	Standard implementation of the federation service interfaces.

Package wt.federation Description

The federation service (wt.federation package) provides functionality to create and manage proxy objects of remote systems and perform utility functions supporting the federation system.

Design Overview

The federation service is designed to be a plug and play component in the Windchill system. The federation service is intended to be used for both client and server development. Business objects, asserted as being federated in the object model, are assigned a remote system information (serviceID) at creation and can be promoted throughout the defined phases of an associated federation. The proxy source information is held in the serviceID cookie, but instead operate on it through the federation service’s external interface. The following figure contains a representation of the object model for federation service.

External Interface

The Federated interface provides an abstraction of a plug-and-play component. The intent is that, in an object model, a business object would assert that is Federated by implementing the Federated interface. With this assertion, the business object can then be created as a proxy of remote object.

The FederationHelper provides an abstraction as the API to the FederationService. The API’s method can be categorized as either local or remote invocations. The local methods are getters of information, typically from cookies that are held in the business object. The remote methods serve as wrappers to a service that promotes server-side functionality.

The FederationService provides an abstraction that specifies and promotes serverside functionality as a service that is remotely available for use by a client. The intent is that this interface defines all the necessary server-side functionality for federation.

The FederationServerHelper provides an abstraction of server-side API to the federation services. These methods can be invoked only from server-side processing.

The FederationServicesException provides an abstraction of an abnormal occurrence or error in usage or processing of the federation service. This exception can be localized through a given resource bundle, and other exception can be nested with in it.

Business Rules

As defined by the standard federation service access control rules, no constraints are placed on the access of proxy objects.

Event Processing

The federation service is an event listener. The service listener listens for and acts upon the following standard Windchill events.

When a PRE_STORE or a PRE_MODIFY event is emitted for a proxy object, the federation service provides the opportunity to store or

update associated objects prior to storing or updating the proxy object itself by doing:

if ( obj instanceof Federated )

((Federated)obj).prepareForStore ();

Revising a proxy object is not allowed. Proxy objects are created against source objects from remote system. The revision is prevented to ensure that the proxy objects are consistent with the source objects.

When a POST_STORE or a POST_MODIFY event is emitted for a proxy object, the federation service provides the opportunity to store or update associated objects after storing or updating the proxy object itself by doing:

if ( obj instanceof Federated )

((Federated)obj).postStore ();

When a PREPARE_FOR_MODIFICATION is emitted for a proxy object, the federation service will throw an exception with a message indication that updating federated objects is not allowed.

Standard Federation Service doAction() and sendFeedback()

The Standard Federation Service-doAction() Executes one or more Info*Engine tasks selected by a specific logical action name, and the types and physical locations of a specific set of objects passed as parameters. sendFeedback() sends feedback objects to the client.

Design Overview

The Federation Send Feedback mechanism uses the Info*Engine Web EventService (WES) to enable the sending of Feedback objects to clients. The Info*Engine WES requires a Message Oriented Middleware (MOM) product to be installed, configured and started. More information about MOM can be found in the Info*Engine Installation and Configuration Guide.

The MOM has to be configured to recognize the "CommandDelegateFeedback" Event. Actually the Event name only has to be the same as the EVENT parameter value for the "Subscribe-Event" webject in the wt/federation/StandardFederationServicesStartup Info*Engine task and the "Emit-Event" webject in the wt/federation/CmdDelegateFeedbackEmit Info*Engine task. These tasks are shipped with EVENT set to "CommandDelegateFeedback". It’s possible to change the value in these tasks to something other than "CommandDelegateFeedback" although I don’t know that it is necessary to advertise this.

For sendFeedback() to work, Federation has to subscribe to receive Info*Engine WES Events, specifically the "CommandDelegateFeedback" Event. This is done via the wt/federation/StandardFederationServicesStartup task, which can be executed at Federation Service startup time. For this task to execute during Federation Service startup, the following line must be added to wt.properties: wt.federation.task.startup=wt/federation/StandardFederationServicesStartup.xml. If the StandardFederationServicesStartup task is executed during Federation Service startup and no MOM is installed/started, Federation Service startup (and Method Service startup) continue it just means that sendFeedback() won’t work if it is called.

Also, if the Federation Verbose flag is true, the following message is logged to the Method Server log file when the Federation Service is started:

Wed 6/13/01 20:00:53: main: wt.federation.StandardFederationService.performStartupProcess() - caught IEException. The nested exception is:

javax.jms.JMSException: java.net.ConnectException: Connection refused: no further information: tcp://<server>:<port>.

The most likely cause is no Messaging Service is started. This is a non-fatal condition. The only consequence is that Command Delegate Feedback is disabled. The stack trace follows.

If the StandardFederationServicesStartup task is executed and the MOM isn’t configured with the proper Event (i.e., the CommandDelegateFeedback Event), the following message is logged and the Method Server terminates.

Tue 6/19/01 20:28:22: main: *ERROR*: (com.infoengine.util.IEResource/115) com.infoengine.exception.fatal.IEFatalServiceException: Lookup of Administered object with uri "CommandDelegateFeedback" returned null.

Similar results will occur (i.e., something will be logged for the error and the Method Server terminates) if the

StandardFederationServicesStartup task is executed and there are other MOM configuration errors.

If sendFeedback() is called and no MOM is installed/started (regardless of whether or not the StandardFederationServicesStartup task was executed), sendFeedback() throws a FederationServicesException exception and, if the Federation Verbose flag is true, the following is logged to the Method Server log file:

Tue 6/19/01 18:57:30: SocketThread0: wt.federation.StandardFederationService.sendFeedback() caught exception.

The stack trace follows.

If sendFeedback() is called without executing the StandardFederationServicesStartup task at Federation Service startup time (and a MOM is installed/configured/started), no Feedback message is sent to the client. In this scenario no errors occur on the Server so there are no exceptions from sendFeedback() and no log messages in the MethodServer log file. The only indication that something is wrong is that the client isn’t receiving Feedback messages.

If sendFeedback() is called without executing the StandardFederationServicesStartup task at Federation Service startup time (and a MOM is installed/started but not configured with the CommandDelegateFeedback Event), sendFeedback() throws a FederationServicesException exception and, if the Federation Verbose flag is true, the following is logged to the Method Server log file:

Wed 6/20/01 14:15:36: SocketThread1: wt.federation.StandardFederationService.sendFeedback() caught exception.

The stack trace follows.

External Interface

This is a supported API. The corresponding UI in Windchill is the Delegate Administrator.

Event Processing

doAction executes one or more Info*Engine tasks selected by a specific logical action name, and the types and physical locations of a specific set of objects passed as parameters. sendFeedback sends feedback objects to clients.

doAction

Example

import wt.federation.FederationHelper;
import wt.util.WTException;
import com.infoengine.object.factory.Att;
import com.infoengine.object.factory.Element;
import com.infoengine.object.factory.Group;
import com.ptc.core.util.feedback.common.FeedbackSpec;
import java.util.Enumeration;

public class DoActionExample {

    public static void main (String[] args) {
        Element testElement = new Element();
                testElement.addAtt( new Att("obid",
                "VR:wt.part.WTPart:73694:551318183-990560613281-2091086-126-8-253-
                132@Windchill.mn.ptc.com") );
        testElement.addAtt( new Att("name", "ENGINE") );
        testElement.addAtt( new Att("number", "2623844395") );
        testElement.addAtt( new Att("CLASS", "wt.part.WTPart") );
        Element[] elementArray = { new Element("arrayElement1"),
        new Element("arrayElement2") };
        Group group1 = new Group( "group1" );
        group1.addElement( group1Elem1 );
        group1.addElement( group1Elem2 );
        ...
        try {
            Object[][] argv = { {"testElement", testElement },
            {"group1", group1},
            {"elementArray", elementArray},
            {"bool1", new Boolean(true)},
            {"char1", new Character(a')},'
            {"int1", new Integer(100)},
            {"byte1", new Byte((byte) 9)},
            {"double1", new Double(10000)},
            {"short1", new Short((short) 99)},
            {"float1", new Float(100.25)},
            {"long1", new Long(4000)},
            {"string1", "argv Test String"} };
            // Federation Service doAction() is accessed through
            // FederationHelper
            Group resultGroup =
            FederationHelper.doAction( "testAction", argv );
            //Example calling doAction() with a FeedbackSpec object.
            Object key = TdTest.class.getName();
            FeedbackSpec feedbackSpec = new DefaultFeedbackSpec(key,
                        true);
            Group resultGroup =
            FederationHelper.doAction( "testAction", argv,
                        feedbackSpec );
            if ( resultGroup != null ) {
                System.out.println( "resultGroup:" );
                showIeGroup( resultGroup );
            } else {
                System.out.println( "resultGroup is null." );
            }
        } catch ( WTException exc ) {
            ...
        }
        ...
    }

    private static void showIeElement(Element inElement) {

        Enumeration attrs = null;
        Att attr = null;
        if ( inElement != null ) {
            System.out.println( "Element:" );
            System.out.println( " Element Name: " +
            inElement.getName() );
            System.out.println( " Element Attributes:" );
            attrs = inElement.getAtts();
            while ( attrs.hasMoreElements() ) {
                attr = (com.infoengine.object.factory.Att)
                attrs.nextElement();
                System.out.println( " " + attr.getName() + ": " +
                attr.getValue() );
            }
        }
    }


    private static void showIeGroup(Group inGroup) {

        if ( inGroup != null ) {
            Enumeration elements = null;
            System.out.println( "Group:" );
            System.out.println( "Group Name: " + inGroup.getName() );
            System.out.println( "Number of Elements: " +
            inGroup.getElementCount() );
            System.out.println( "\nGroup Elements:" );
            elements = inGroup.getElements();
            while ( elements.hasMoreElements() ) {
                showIeElement( (Element) elements.nextElement() );
            }
        }
    }
 }

sendFeedback

Example

import wt.federation.FederationServerHelper;
import wt.federation.FederationServicesException;
import wt.feedback.StatusFeedback;

public class SendFeedbackExample {

    public static void main (String[] args) {
        ...
        try {
            // Send the client a StatusFeedback type feedback object.
            // Federation Service sendFeedback() is accessed through
            // FederationServerHelper.service
            FederationServerHelper.service.sendFeedback(
                new StatusFeedback( "Test Feedback Message" );
        } catch ( FederationServicesException exc ) {
            ...
        }
        ...
    }
}