Teamcenter Global Services Customization Guide. Publication Number PLM00091 J

Transcription

1 Teamcenter 10.1 Global Services Customization Guide Publication Number PLM00091 J

2 Proprietary and restricted rights notice This software and related documentation are proprietary to Siemens Product Lifecycle Management Software Inc Siemens Product Lifecycle Management Software Inc. All Rights Reserved. Siemens and the Siemens logo are registered trademarks of Siemens AG. Teamcenter is a trademark or registered trademark of Siemens Product Lifecycle Management Software Inc. or its subsidiaries in the United States and in other countries. All other trademarks, registered trademarks, or service marks belong to their respective holders. 2 Global Services Customization Guide PLM00091 J

3 Contents Proprietary and restricted rights notice Getting started with customizing Global Services Getting started with customizing Global Services Before you begin Global Services components Interactive data source access Global Services message flow Local language support Sample files Creating data source connectors Creating data source connectors Understanding connectors Defining connectors Implementing connectors Using connectors Extending Global Services connectors Deploy a custom connector Developing your connector ICD file Creating initiators Creating initiators Understanding initiators Implementing an initiator Creating reactors Creating reactors Understanding reactors Defining reactors Implementing reactors Using reactors BOSClient class Implementing transfer and synchronize functionality Deploying a custom reactor Customizing the user interface Customizing the user interface Creating action components, JSP pages, and response chains Application map links JSP pages Building forms and tables Using links in the user interface PLM00091 J Global Services Customization Guide 3

4 Contents Using style sheets Presentation elements Supporting local languages Supporting local languages Using ID maps Using localized transformation files Using text bundles Exception and message handling Exception and message handling Exceptions Message localization and logging Exception coding and logging conventions Configuring debug message logging Using the convenience classes Using the convenience classes BOSClient class methods Traversing business objects Caching the BOSClient object DataObject class Additional convenience methods Sorting search results Creating a custom security service Creating a custom security service Tailoring a BPEL process Tailoring a BPEL process How BPEL framework works Create and deploy a Web service for BPEL Best practices Adding a pre-export step to the data transfer process Create a BPEL project Add a new process step Package and deploy the process Deploy a custom BPEL process to Global Services Installable component descriptor (ICD) files A-1 ICD file naming conventions A-1 ICD tags A-1 warpackager utility A-7 Glossary B-1 Index Index-1 4 Global Services Customization Guide PLM00091 J

5 Chapter 1 Getting started with customizing Global Services Getting started with customizing Global Services Before you begin Global Services components Interactive data source access Global Services message flow Local language support Sample files Sample connector Sample JDBC connector extension Sample exception subclass Sample initiator Sample reactor Sample action handler Sample of a service that access BPEL process Sample utilities Additional examples PLM00091 J Global Services Customization Guide

6

7 Chapter 1 Getting started with customizing Global Services Getting started with customizing Global Services Global Services components are based on application server technology, Enterprise JavaBean (EJB) standard coding, and the Extensible Markup Language (XML). Before you begin Prerequisites Depending on the type of customizations you intend to perform, you should possess some or all of the following skills: Experience in software development and a moderate understanding of Sun s Java programming language. A basic understanding of Enterprise JavaBeans (EJBs). Knowledge of XML, XSL, and HTML. Basic knowledge of JavaServer Pages (JSP). Knowledge of Web Services Description Language (WSDL) and Business Process Execution Language (BEPL) may also be helpful. The development platform you use must meet the requirements for running Global Services. For information about versions of operating systems, third-party software, and Teamcenter software that are certified for your platform, see the Siemens PLM Software Certification Database: certification/teamcenter.shtml In addition, you must have Java SDK 1.5 (5.0) or a later version installed. PLM00091 J Global Services Customization Guide 1-1

8 Chapter 1 Getting started with customizing Global Services Configure customization To compile most custom components based on the Global Services sample files, you must have the globalservicescore.jar file included in your CLASSPATH environment variable. Additionally, to run a custom initiator, you must have any JAR files required by the message server that your initiator communicates with in the CLASSPATH environment variable. As part of the Web application installation process, you installed the Teamcenter 10.1 Global Services Application Directory solution. The staging directory for this solution contains a copy of the required globalservicescore.jar file in its lib directory. The example directory contains the sample files. Global Services components Global Services contains the following customizable components: Action and response handlers Global Services provides a user interface for data capture and page rendering using action and response handlers. These handlers provide an interface to the core features of Global Services. User actions that require the use of a request input stream or the response output stream are implemented as response handlers. An action related to uploading or downloading a file is implemented as an action handler. The handlers are accessed through a URL call. JavaServer Pages (JSP ) Global Services uses JSP functionality to provide the administrative interface into the Global Services datastore. Global Services published APIs Standard Global Services provides a published API for all core features. Business object server (BOS) The Global Services BOS is an EJB that processes a client request and dispatches it to the applicable connectors. Connectors A connector is an EJB that provides a common data access mechanism that isolates the data source from other components. Connectors are required for all data sources that contain data you want to use in any of your business objects. The BOS communicates with the data source through the connector. Message server The Global Services message server is an EJB that processes a specific message request. Reactors 1-2 Global Services Customization Guide PLM00091 J

9 Getting started with customizing Global Services A reactor receives a notification when the Global Services message server receives messages of specific types. The reactor processes the message information and determines the action that is required. Initiators An initiator is a custom component containing logic that is capable of sending a Global Services client request from a data source to the Global Services message server through a Java Message Service (JMS) queue. An initiator is used to notify reactors of an event that has occurred relative to the originating data source. Datastore Global Services stores all runtime files, such as configuration files and security files, in a datastore. This datastore is a JDBC compliant database configured as a data source in your applications server. JMS message support Message requests from external sources are routed through the Global Services message server through a JMS. JMS can also be used to pass message requests among reactors.global Services uses message driven beans (MDBs) as JMS listeners that respond to JMS messages from a message queue. Message logging and debugging Global Services supports the log4j message logging for transactions, errors, warnings, and debugging. Message logging can be configured to use a local message log or a remote message log for centralized logging. Security Global Services supports application server security and Teamcenter single sign-on (SSO) security. For data source security, you can configure Global Services to use one of four security mechanisms: XML file-based security, LDAP security, SSO credential service, or a custom security mechanism. The SSO credential service allows a user to log in to Teamcenter Global Services and access multiple data sources with the appropriate user name and password for the data source provided automatically by Global Services. A lightweight directory access protocol (LDAP) mechanism is the intended source for the repository of sign-on credentials Global Services runs on an application server in conjunction with a Web server. The application server provides an Enterprise JavaBean (EJB) container and a servlet container that are part of the distributed object foundation where Global Services is deployed. Global Services provides action handlers as Web Services that are published in Web Service Description Language (WSDL). Interactive data source access The following figure shows the data flow from your users to a data source and how object information is returned to the user. Users dynamically interact with Global Services using a Web browser over standard HTTP and HTTPS protocols. The Web interface uses a combination of HTML files, Web services, and JSP pages. You can customize this interface in a variety of ways. PLM00091 J Global Services Customization Guide 1-3

10 Chapter 1 Getting started with customizing Global Services Client Request Client Tier Presentation Tier Framework Login Manager Authentication Presentation Tier (Servlet Container) Presentation Tier Framework Action Handler 1 Response Handler Shared Services Log4j I18n Action Handler n SSO L10n Global Services Client API Global Services Data Store Manager Global Services Connection Manager Enterprise Tier (Application Server) AppSvr Security OMfg Connector Connection Oracle Manufacturing TcEngineering Connector Teamcenter Engineering Shared Services Security Services LDAP XML SSO Custom Log4j I18n BOS TcEnterprise Connector SAP Connector Teamcenter Enterprise SAP SSO L10n Data Store Server JDBC Connector Resource Tier Data Store Database Global Services action handlers use the Global Services client API (BOSClient interface) to communicate with the business object server (BOS). The BOSClient interface is a convenience class that hides the details of linking to connectors, such as the BOS, and calls the individual connector methods. The BOSClient class also provides utility methods to perform the following tasks: Return business object metadata information. Obtain local language display text for business object labels. Convert a list of data objects (business object instances) to XML. The BOS is a special instance of a connector that provides access to enterprise business objects. Business objects are an abstract definition of data that can reside in one or more data sources. Business objects are defined using simple XML configuration files. All communication with the BOS is done in terms of business objects. The BOS translates the requests into the necessary calls to gather the information and return the data in a generic data object format. The data object allows the attribute data to be easily extracted without having to understand the details of the business object definition. The BOS provides a level of indirection 1-4 Global Services Customization Guide PLM00091 J

11 Getting started with customizing Global Services between interoperating systems. This level of indirection allows individual systems to be modified or replaced without impacting existing system interoperability. Connectors are required for any data source that supplies data to a business object. A connector provides a common interface to access business object information by implementing the Global Services-defined Business Object extension (BOX) interface. Global Services provides a connector for JDBC-compliant databases. Global Services contains additional connectors that you can purchase as needed. You must create a custom connector for any other data source requiring information exchange through Global Services. A sample connector implementation is included that you can use as a starting point for defining custom connectors. For more information, see Sample connector. Global Services message flow The following figure shows how Global Services provides communication of events. The Global Services message server is the backbone of interoperability communication within Global Services. The Global Services message server provides a data neutral method of communication of significant messages produced by an application publisher and consumed by any number of reactor subscribers. A message is a notification of a significant occurrence within a particular component domain of which other components must made be aware. Occurrences requiring message notification may include object creation, modification, deletion, and so forth. The messages are delivered to Global Services in the form a standard URL, for basic delivery, or as an XML message for JMS delivery. Client Tier Client Request Presentation Tier Framework Login Manager Authentication Presentation Tier (Servlet Container) Action Handler Shared Services I18n Log4j L10n AppSvr Authentication Enterprise Tier (Application Server) Qn Q1 Shared Services Security Services LDAP XML SSO Custom MDB n Custom Initiator Log4j L10n I18n Message Server MDB 1 JMS Provider Authentication Reactor 1 Reactor n PLM00091 J Global Services Customization Guide 1-5

12 Chapter 1 Getting started with customizing Global Services The basic Global Services message system consists of initiators, action handlers, the Global Services message server, and reactors. Initiator is a general term applied to any data source mechanism that is used to send a URL or XML-formatted message to Global Services. Global Services includes an example of a standalone, Java application initiator. You can use the sample initiator in either interactive or command line mode. Interactive mode allows you to manually compose a message. You can use the command line mode for automatic message submission based on an application trigger. For more information, see Sample initiator. Message URLs are received by the publish action handler. This handler processes the messages passed from the Web server or initiator, performs rudimentary validation, packages the data in an object format, and calls the Global Services message server for message delivery. The Global Services message server maintains a mapping of reactors and the messages in which they are interested. The mapping is specified through an XML configuration file. When a message is received, the Global Services message server first records the message information in the message log. The Global Services message server then invokes each reactor registered for the message in turn. The results of the reactor processing are written to the message log after each reactor completes its processing. A reactor is an implementation of business logic typically associated with a particular task or specific data domain. Reactors examine the message information to determine what, if any, action is required. A reactor uses the client interface to obtain additional information or perform tasks associated with business objects. Global Services includes a sample reactor implementation to illustrate common interactions using the client interface. For more information, see Sample reactor. Global Services also provides the notifier which is a specialized reactor implementation. The notifier provides notification or data logging when specific messages are received. The notifier message rules, actions, user lists, and text are easily specified through an XML configuration file. For information about the notifier configuration file, see the Global Services Configuration Guide. Additionally, Global Services supports message delivery through a JMS queue. The Global Services MDB provides the communication link between the JMS queue and the Global Services message server. The initiator provides XML-formatted or URL-formatted messages for JMS delivery. Global Services provides asynchronous and synchronous JMS interfaces for use between the JMS queue and an initiator or the publish action handler. The interface between the publish action handler and the JMS queue allows messages that enter Global Services in URL format to use the JMS delivery feature. The publish action handler translates the URL message into an XML-formatted message that the JMS queue requires. Global Services provides sample asynchronous and synchronous JMS interfaces based on the Global Services JMS interfaces. You can use these interfaces to connect your custom initiator to a JMS queue or you can build your initiator to connect directly to the JMS queue. For more information, see Sample initiator. 1-6 Global Services Customization Guide PLM00091 J

13 Getting started with customizing Global Services Local language support Global Services supports dynamic localization of presentation information. The following figure shows how Global Services provides locale-specific content. The user s browser locale is written to the session at logon time. This locale is used to provide information, other than data source supplied data, in the user s selected language. The business object can define text IDs and default display text for the object name, attribute names, and link names. The BOSClient class uses text IDs to retrieve the corresponding text from the ID map associated with the user s locale when generating the XML output file. The BOSClient class methods are used to retrieve the localized display text for a business object. Application Server Java Virtual Machine (VM) EJB Container Servlet Container Web Server Connector EJBs BOS EJB JSP Action Component X S L T HTML Server Locale Only Locale TextBundles BOSClient XML Common XSL XSL XSL Locale Client (browser) Data Source BOD XML Locale IDMap Generic object Data source specific object Source supplied language (browser or data source) Dynamic supplied language (nondata components only) Messages supplied in server s locale Action components use the BOSClient class to obtain localized XML representation of the business object data. XSL style sheets are applied to the XML to produce HTML presentation data for some user actions. For other user actions, the objects are passed to JSP pages that produce HTML based on the object content. The Global Services user interface provides XSL style sheets to produce error reports, install status, message results, and operation results. The XSL style sheets are divided into locale-specified and locale-neutral components. Each type of XSL style sheet has a separate definition for each defined locale. The locale-specific definitions include XSL variables that define the language specified text that appears in the output HTML. You can also use the locale-specific style sheets to define locale-specific display information such as colors and fonts. The locale-neutral components are the actual XSL transformation rules. The rules are separated from the locale-specific definitions. There is only one set of locale-neutral rules for each XSL style sheet type. Each locale-specific style sheet definition includes a set of locale-neutral rules to form a complete XSL style sheet PLM00091 J Global Services Customization Guide 1-7

14 Chapter 1 Getting started with customizing Global Services definition. By default, the rules convert the XML format data to HTML by using the locale-specific variables. You can replace the common rules for one or more of your locales if you want locale-specific presentation of the data. Global Services components use TextBundle classes for all internally generated messages. Also, Global Services JSP pages use the TextBundle classes to generate locale-specific static text. A TextBundle class is an extension of the standard Java ListResourceBundle class that contains a text ID associated with message text. You can define TextBundle classes for a specific package and create a separate class for each supported language. You use the TextBundle class for your own localizations. Sample files Sample component files are provided for connectors, reactors, initiators, action handler (sample action components, response chains, JSP), utilities, and an exception subclass. You can use these files as a guide for creating your own component. These files are located in the associated staging-directory\webapp_root\example\component directory (staging-directory/webapp_root/example/component directory for UNIX). For more information about the example classes, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. Note There is a build file for each sample. All required JAR files for the samples, except for the j2ee.jar file, are in the lib directory under the webapp_root directory. The build files look for j2ee.jar file relative to the J2EE_HOME environment variable. Alternatively, you can put the path to the j2ee.jar file in the CLASSPATH environment variable. The ActionChain example requires that you copy the wae.jar file from the teamcenter_wae.jar Web Application Manager component to the lib directory under the webapp_root directory. Sample connector Global Services connectors, action components, and the BOSClient API interface all work together to make it easy for you to provide data source information to your users. The sample connector included with Global Services shows the basics of what you must do to create your own data source connectors. Because this example represents a connector to a nonexistent data source, hardcoded data is used to simulate the remote data. The ExampleBoxBean class provides the main code for this example connector. This connector shows what is required for you to connect to any external data source, such as a database, a legacy application, or some form of network resource. You must implement the methods required by all EJBs and the methods for the connector BOX API, based on what your data source supports. The example provides a simple connector for a business object with two attributes. The query, insert, delete, and update methods are provided along with an execute method. The execute method provides a generic interface that allows you to use specialized functions for your data source. The ConnectionBox class defines the basic interface that all connectors must implement. The abstract ConnectionBoxBean class provides default 1-8 Global Services Customization Guide PLM00091 J

15 Getting started with customizing Global Services implementations for the ConnectionBox methods. The ConnectionBoxBean implementation provides common services, such as using the single sign-on credential service to look up user IDs and passwords. The sample connector classes, like all custom connectors, extend these classes to create the basis for the connector implementation. Data is passed to and from the connector in DataObject class instances. The information contained in the data objects at the connector level is always in terms of the data source. The connector retrieves information passed in the generic data object that it uses when communicating with the data source. The connector packages information received from the data source in a data object returned to the caller. The sample connector illustrates this type of interaction. Sample JDBC connector extension Global Services provides a sample extended JDBC connector that shows the basics of what you must do to add custom functionality to the JDBC data source connector. This example extends the execute method to include a meta function that returns the JDBC connection product name and version. For more information, see Extending Global Services connectors. Sample exception subclass The sample exception subclass provided with Global Services consists of four sample class files required to create a custom Global Services exception subclass. The example has the following classes that you need to implement for your custom exception class: TextBundleIDs The TextBundleIDs.java file that contains the message ID strings. TextBundle The TextBundle.java file that contains the user interface exception message and exception title strings. Locale TextBundle The TextBundle_xx_xx.java files that contain the user interface exception message and exception title strings for a specific locale. GlobalServicesException The ExampleGlobalServicesException.java file that contains the constructors and methods that you implement for your custom exception. The sample files contain information that you need to create custom Global Services exceptions. You must add your text bundle strings and constants, implement the required constructors, and override the getexception, getuititleid, and getuistorename methods of the sample exception class. For more information, see Create a custom exception class. PLM00091 J Global Services Customization Guide 1-9

16 Chapter 1 Getting started with customizing Global Services Sample initiator The sample initiator is a standalone Java application that can generate Global Services messages in interactive or command line modes. There are six sample classes provided in the initiator example. These six classes are provided as a reference implementation for sending messages to the Global Services message server or a JMS queue. The Initiator class is an application (provides a main method) that accepts command line arguments representing the content of the message to be sent to the Global Services message server. This interactive method is provided as an easy way to test and debug message configurations and is not intended for use in your final product. The InitiatorDialog class provides an interactive swing-based dialog for sending messages to the Global Services message server or a JMS queue. A companion Global Services Message Server Administration dialog box is also implemented in this class. The access button for this window is commented out so that it is not available in the standard example. You can uncomment this code to obtain that functionality. The InitiatorMessage class handles Global Services messages that are sent to the Global Services message server or a JMS queue. The InitiatorMessage class sends URL-formatted Global Services messages or URL-formatted XML text messages to the publish action handler. The action handler formats the message appropriately and sends it to either the Global Services message server or the JMS queue set. This class can be imported and used independently within other Java development. Global Services provides three additional reference implementations that support JMS queues. The SendMessage class is the base class for the SendMessageAsynch and SendMessageSynch classes. The SendMessage class provides the following methods common to both synchronous and asynchronous JMS delivery. Initializes the JMS queue. Sets the action and response queues to use. Establishes the connection. Sets the session security context. Closes the connection. The SendMessageAsynch class provides the send and receive methods specific to asynchronous message delivery. Asynchronous messages are delivered the JMS queue and do not require a response. The SendMessageSynch class provides the send and receive methods that are required to send synchronous messages. Synchronous messages are delivered to the JMS action queue and a response must be returned to the response queue. For more information, see Creating initiators. Sample reactor The ReactorBean class provides default implementations for the required EJB methods. Because reactors are stateless session beans, the ejbactivate and ejbpassivate methods are never called by the container. Because the default implementations do not have to be overridden, this example does not override those methods. The example reactor also uses the ReactorBean class implementations of the setsessioncontext and getsessioncontext methods. The default implementation is sufficient for most reactors. The reactor ejbcreate and 1-10 Global Services Customization Guide PLM00091 J

17 Getting started with customizing Global Services ejbremove methods are overridden only to supply context-sensitive messages to the standard output log. Your reactor can contain common logic that can be shared with other components. To do this, define public functions and add them the remote interface so that they can be accessed by other EJBs, action components, or applications. The example provided implements the onglobalservicesmessage method that is the Global Services message server callback method, along with acronym manipulation methods used in conjunction with the other example components. These acronym methods can be used as a guide to how to a reactor participates in creating (insertacronym), deleting (deleteacronym), and updating (updateacronym) objects. They are declared as public methods in the example only so that they are included in the online class documentation (Global Services Javadoc). They can be declared private without loss of function. The example implements a setconfigvariables method that shows how you can set reactor configuration variables at runtime based on the values in a configuration file. Configuration files are not required and reading them can have a negative impact on system performance. A reactor that communicates with connectors, either directly or through the Global Services message server, must provide a user ID to establish a connection to the data source. Reactors are trusted components of the Global Services systems and, therefore, do not required passwords. The reactor simply passes the user ID without a password when connecting to the BOS or other connector. The connector itself uses the single sign-on credential service to determine the appropriate user ID and password to use when connecting to the actual data source. A reactor can require that callers of the public interface provide the user ID and a password. However, the reactor itself must provide a user ID when the onglobalservicesmessage method is called by the Global Services message server. The user ID can be obtained from a configuration file, but the example provides them as hardcoded values. The example uses the GlobalServicesMessage.getMap method to retrieve a map containing all of the parameters and uses the map to act on the message content. The source_attr_names keys appear in the map with a class. prefix. Sample action handler The staging-directory\webapp_root\example\actionchain directory provides examples of action handler components you can use to create your own action handlers. The examples show how you typically create action components using the GetBODActionComponent and UpdateBODActionComponent classes, a JavaServer Pages (JSP) page, and the application map file. For information about using the sample action handler, see the README.txt file provided with the sample files. For detailed information about action handlers, see Customizing the user interface. Sample of a service that access BPEL process The staging-directory\webapp_root\example\service directory provides and examples of a Web service. The example show how to create Web service in Global Services that can be used tasks such as accessing a Global Services BPEL process. For information about using this example, see Create and deploy a Web service for BPEL. PLM00091 J Global Services Customization Guide 1-11

18 Chapter 1 Getting started with customizing Global Services Sample utilities The sample files also contain several utility classes. These classes are located in the staging-directory\webapp_root\example\util directory (staging-directory/webapp_root/example/util directory for UNIX). Although they can be used by any component, they are particularly useful when implementing JMS delivery in your initiator. Global Services provides the following utility class files: ObjectInitializer.java Initializes and instantiates an object from a set of properties. For JMS delivery, can be used to initialize the QueueConnectionFactory specified in the initiator.properties file and create connections to the JMS message server. PasswordAuthenticator.java Provides user name and password authentication. It can be used by initiators to communicate with action handlers using application server security. StringUtils.java Provides a generic string manipulation method. UnigueID.java Uses the hash algorithm from the java.security package to generate a unique identifier. For JMS delivery, it can be used to generate the message ID for synchronous messages. Additional examples There are several additional sample directories that contain sample files for other types of Global Services customizations. For example, there is a sample BPEL process and a sample extension to the SOA connector (TcExtension directory). See the README.txt files in these directories Global Services Customization Guide PLM00091 J

19 Chapter 2 Creating data source connectors Creating data source connectors Understanding connectors Connector architecture Connector EJB naming conventions Defining connectors Connector home interface Connector remote interface Defining the connector implementation class Implementing connectors Using connectors Identifying connector conformance levels Supporting the query_criteria parameter Creating a connector EJB instance Establishing a data source link Calling connector methods Using the remote interface Connector life cycle Extending Global Services connectors JDBC connector Extending JDBC connectors Teamcenter Enterprise connector Extending the Teamcenter Enterprise connector Using Teamcenter Enterprise specific action handlers Uploading an object Checking in an object Downloading an object SOA connector Deploy a custom connector Developing your connector ICD file PLM00091 J Global Services Customization Guide

20

21 Chapter 2 Creating data source connectors Creating data source connectors Use this information to create Teamcenter Global Services connectors for data sources other than those provided. This information includes a description of how a data source interface is commonly exposed within the Global Services environment. However, this explanation does not attempt to tell you how to write methods to implement a connector to a specific data source. The following information tells you how connectors are used and provide the basic information you need to create connectors for your data sources. Understanding connectors A connector is an Enterprise JavaBean (EJB) that provides a common API to isolate the data source from other components. This allows a common interface to be used for all types of data sources. Connectors are required for all data sources that contain data you want to use in any of your business objects. However, you can use a general purpose connector, such as the Java Database Connectivity (JDBC) database connector, to link to data sources of the same type using deployment configuration variables. Connector architecture A Global Services connector is an EJB that is implemented through three separate Java classes as specified by the EJB standard. The three Java classes represent the connector home interface, the remote interface, and bean implementation. The following figure shows the high-level components and naming conventions used when creating a connector. For more detailed naming information, see Connector EJB naming conventions. PLM00091 J Global Services Customization Guide 2-1

22 Chapter 2 Creating data source connectors Home Interface Remote Interface Implementation EJB Standard Classes EJBHome EJBObject SessionBean Extended by Extended by Implemented by Global Services Base Classes ConnectionBoxHome Extended by ConnectionBox Extended by Implemented by ConnectionBoxBean Extended by Data Source Specific Classes DataSourceBoxHome DataSourceBox DataSourceBoxBean The connector home interface defines the functions that are used to create an instance of the connector. The business object server (BOS) requires all connectors to have one specific create function, but other create functions can be added for specific needs. See Connector home interface. The connector remote interface (connector box API) defines the methods that can be invoked remotely by users of the connector. The remote interface defines the public access methods for the connector. These public methods include the EJB standard methods as defined by the EJBObject class, the common connector methods defined by the ConnectionBox interface, and any data source specific extensions. See Connector remote interface. The connector bean implementation class contains the logic of the connector that connects to the data source. The ConnectionBoxBean class provides implementations for all session bean defined methods. It also provides implementations for all common connector methods defined by the ConnectionBox interface. Connector EJB naming conventions A Global Services connector is an implementation of a stateful EJB. The connector interface and class names must follow EJB standards to ensure proper and error-free deployment. The following naming conventions apply: Home interface Remote interface Implementation DataSourceHome DataSource DataSourceBean DataSource is the base name of the connector that contains the description of the data source or linking mechanism, or both. The Global Services connector remote interface, as defined by the ConnectionBox interface, is referred to as the business object extension (BOX) interface. Therefore, the base name of all connector interfaces and classes supplied with Global Services contain the Box suffix. For example, the Teamcenter Enterprise connector interfaces and classes are TcEntBoxHome, TcEntBox, and TcEntBoxBean. Siemens PLM Software recommends that you follow this Box suffix standard for new connectors that implement only the methods defined by the ConnectionBox interface. Connectors also have a Java Naming and Directory Interface (JNDI) name that identifies the connector at runtime. Connector clients use the JNDI name to uniquely identify a particular connector deployment 2-2 Global Services Customization Guide PLM00091 J

23 Creating data source connectors bean for access to a particular data source type. The default JNDI names for all released Global Services connectors begin with the TcGS prefix. Defining connectors Unless you intend to explicitly add additional methods, define your connector using the ConnectionBoxHome class for the home interface and the ConnectionBox class for the remote interface. The staging-directory\webapp_root\example\connection directory (staging-directory /webapp_root/example/connection directory for UNIX) contains the ExampleBoxHome.java (home interface), ExampleBox.java (remote interface), and ExampleBoxBean.java (implementation class) files. You can use these files as a starting point for defining your connector. Note To compile a custom connector, you must have the globalservicescore.jar file in the CLASSPATH environment variable. Connector home interface The connector home interface is an extension of the interface that defines life cycle operations and metadata for the connector bean. This interface provides a client-side API for creating and removing connector beans. Siemens PLM Software recommends that you use the ConnectionBoxHome interfaces as is. Extend this interface only when you need to provide methods for use outside of the Global Services framework. Connector remote interface The connector remote interface defines the client-side API for the connector. Connectors are only required to provide the interface used by the BOS, as defined by the ConnectionBox interface. Siemens PLM Software recommends that you use the ConnectionBox interfaces as is. Extend this interface only when you need to provide methods for use outside of the Global Services framework. Defining the connector implementation class The connector implementation class contains the code that performs the data source access specific to the connector type. The connector implementation class must extend the base ConnectionBoxBean class to function properly in the Global Services environment. However, your connector class can override any of the methods defined by the ConnectionBoxBean class, provided the superclass method is still invoked. See Implementing connectors. Define the connector implementation class as follows: public class DataSourceBoxBean extends ConnectionBoxBean { // Local variables and methods // Method overrides of ConnectionBoxBean methods // Extension methods defined in the connector remote interface } PLM00091 J Global Services Customization Guide 2-3

24 Chapter 2 Creating data source connectors Implementing connectors To implement a connector home interface, you need only define the interface as described in Connector home interface. This implementation is automatically provided as part of the EJB container system. For the connector remote interface, the ConnectionBoxBean class provides a basic implementation of the home create, SessionBean, and ConnectionBox interfaces, as required by the EJB standard. This implementation of the ejbcreate, connect, and ejbremove methods provides capabilities critical for the proper functioning of the Global Services environment. Because you must override some of these methods to implement a functioning data source connector, Siemens PLM Software recommends that you always invoke the ConnectionBoxBean implementation when overriding any of these functions. Override connector methods as shown in the following example: public void ejbcreate( type1 name1,..., typen namen) { super.ejbcreate( name1,..., namen); // Connector specific code } The default ConnectionBoxBean implementation for other methods defined in the ConnectionBox interface functions as a proxy invoking the method on a ConnectionBoxImpl class retrieved through the getconnectionimpl method. The standard implementation of most methods follow the form: public SerializableCollection<DataObject> query(final String objectname, final WhereClause where, final SerializableCollection<String> attributes) throws GlobalServicesException { return (SerializableCollection<DataObject>) new DestroyingCommand() { public Serializable exec() throws GlobalServicesException { return getconnectionimpl().query(objectname, where, attributes); } }.execute(); } Siemens PLM Software recommends when you implement a ConnectionBoxBean class that you extend the TransientImpConnectionBoxBean class and implement another class that extends ConnectionBoxImpl class. In your ConnectionBoxBean class ejbcreate and ejbactivate methods, call the setconnectionimpl method and pass it a new instance of yourconnectionboximpl class. This makes your bean class a proxy for your implementation. You do not need to override any other methods in the ConnectionBoxBean class. You do not need to override any other methods in the ConnectionBoxBean class. The following are standard ConnectionBoxBean methods: Create method ejbcreate Description Invoked when the connector home create method is called by a connector client. It is called only once during the EJB life cycle. You should override this method to perform any one-time initialization. The superclass function should be called before executing the local implementation. 2-4 Global Services Customization Guide PLM00091 J

25 Creating data source connectors Session bean interface method ejbactivate ejbpassivate ejbremove Description The EJB container invokes this method when activating a passivated connector. You must override this method and reconnect to the data source that was disconnected during passivation. For more information, see Connector life cycle. The EJB container invokes this method when passivating an idle connector to recover system resources. If your are not extending the ConnectionBoxImpl class, you can override this method to shut down the data source connector. When you extend the ConnectionBoxImpl class, the close method performs this action. For more information, see Connector life cycle. Invoked only once during the EJB life cycle, before releasing the EJB instance. If your are not extending the ConnectionBoxImpl class, you can override this method to return any resource to the system that the EJB acquired. ConnectionBox interface methods compute connect delete execute expand insert Description Returns a string that contains the result of a request. In standard Global Services, this interface method is supported in the JDBC connector only. Invoked to establish a data source connector. The default implementation provides automated security lookup to find the appropriate user ID/password for the data source. Override this method to establish a data source link. The superclass function should be called before executing the local implementation. Override this method if the connector supports deletion. A connector client calls this method to call a specialized connector function. You can use the execute method to extend the connector functionality beyond the basic BOX interface. Caution Do not use download, upload, checkin, or checkout as execute extension method names. These names are reserved for Global Services use. Override this method if the data source supports relationships between objects. Override this method if the connector allows creating new objects. PLM00091 J Global Services Customization Guide 2-5

26 Chapter 2 Creating data source connectors ConnectionBox interface methods query update Description Override this method to provide the basic connector functionality of returning data source information. Override this method if the connector supports updates. The ConnectionBoxBean class also contains the following data access methods for setting and retrieving local variables: Method getconfig getconfigname getconnectionimpl getlocalwildcardinfo getoriginalwildcardinfo getparameter getparametermap getpassword getsessioncontext getuserid getuserpassword isenabled setsessioncontext setusernamepassword Description Returns the bean s ConnectionBoxConfig instance. Returns the configuration file name value. Returns the bean s connection implementation object. Returns the wildcard information for the connector. Returns the characters that are string and positional wildcard attribute values as defined in the connector configuration file. Returns the string value of a parameter defined in the connector configuration file. Returns all configuration parameters defined in the configuration file for the connector. Returns the password that is used to link to the data source. The password returned is determined automatically if a null password was passed to the connector from the create method. Returns the session context for the connector bean. You can use the session context to retrieve environment and other local variables. Returns the user ID that is used to link to the data source. The user ID this method returns does not have to match the user ID passed to the connector from the create method. Returns the user ID and password from the security file. Returns the value of the enabled element from the connector configuration file. Sets the associated session context. Sets the user name and password stored by the bean. 2-6 Global Services Customization Guide PLM00091 J

27 Creating data source connectors Using connectors The Global Services connector class provides a default EJB implementation for all required methods. You can override or reuse the default implementations as necessary. Using a connector to communicate with a data source only requires that you invoke an EJB method. To use a connector to query a data source, you must supply the following data: Item JNDI name Config name User ID Password Name where clause Select list Max items Description The JNDI name of the connector EJB established when it was deployed. The name of the XML configuration file that controls the information required to establish a connection to the data source A valid user ID used for connecting to the data source. For more information, see the following password item description. Optional password for the supplied user ID for the data source. If the password is not specified, the connector uses the Global Services single sign-on mode. Single sign-on mode attempts to determine the local user ID and password for the data source through the Global Services security interface. The type name of the data items requested, typically a business object name. This name is dependent on the connector implementation, but is typically a class name for an object oriented data source or a table name for a database-oriented data source. The expression used to select one or more data items. The format of the where clause is similar to the form of an SQL where clause. The degree of SQL conformity is dependent on the connector implementation. A list of attribute values returned for the specified data item type. In general, a select list must be specified. However, specific connector implementations, such as the business object server, may choose to provide a default attribute list. An optional limit on the number of data items returned. This is used to improve performance. Identifying connector conformance levels It may be difficult to implement a fully functional BOX interface for all data connectors. Therefore, you write connectors to various Global Services conformance levels. These levels are determined by the level of support for the where clause parameter. Global Services defines the following conformance levels: Level Simple Definition Supports simple equality expression with no masking or wildcard characters. PLM00091 J Global Services Customization Guide 2-7

28 Chapter 2 Creating data source connectors Level Basic Teamcenter Full Nonconforming Definition Supports the Global Services query_criteria expressions with no masking or wildcard characters. For more information, see Supporting the query_criteria parameter. Supports the Global Services query_criteria expressions including masking or wildcard characters. For more information, see Supporting the query_criteria parameter. Supports the full SQL expressions including masking or wildcard characters. Supports non-where criteria unique to the individual data source. Clients must be aware of the nonconforming interface when requesting information from the connector. The sample Global Services user interface may not be able to communicate with a nonconforming connector. Global Services architecture does not enforce or report the conformance level. Supporting the query_criteria parameter The Global Services query_criteria parameter is a subset of the SQL WHERE clause expressions. It specifies the criteria objects must meet to be included in the connector method being called. Objects not meeting the criteria are not used in the operation. Criteria expressions are any number of conditional expressions separated by the logical AND or OR operators. The conditional expressions are of the form: value comparison-operator value The valid value expressions are described: attribute name Specifies a class attribute. Names must match exactly and are case sensitive. Do not use locale-specific names. character literal Character data enclosed in single quotation marks ( ). numeric data Numbers not enclosed in punctuation. NULL The NULL keyword is valid only with the IS comparison operator. Valid comparison-operator entries include the following: < (less than) <= (less than or equal to) = (equal to) > (greater than) >= (greater than or equal to)!= (not equal to) 2-8 Global Services Customization Guide PLM00091 J

29 Creating data source connectors IS [NOT] NULL (determines if an attribute exists; only comparison operator allowed for binary attributes) LIKE (pattern matching using SQL masking characters) Global Services provides the ConfigFactory class that contains the getconfigforspec method. This method can be used to access the configuration for a specified bean and the getwildcardinfo method can be used to get the wildcard characters specified in the XML configuration file. This file provides configurable global (match any number of characters) and positional (match a single character) masking characters in addition to an escape character. The escape character is used to allow the user to enter the global or positional masking character to be used as a literal character in a where clause. For more information about this file, see the Global Services Configuration Guide. The Global Services supplied user interface provides information on the search form that indicates what characters are used for the masking and escape characters. The BOS substitutes any masking characters in a case insensitive where clause containing a LIKE operator that is generated from the standard search form, with the masking characters required in the where clause for the data source-specific connector. The Global Services supplied JDBC connector is configured in the sample objects to use the percent (%), underscore (_), and back slash (\) characters for string, positional, and escape characters. However, any characters that are supported by the JDBC database can be used. The escape character is set in the SQL statement with the SQL clause. The Global Services user interface limits user actions to a single object for all functions except queries. Therefore, if you use the sample objects, masking character substitution is limited to queries. The BOSClient class allows you to use the masking character substitution functionality with other methods. For more information, see BOSClient class methods. Creating a connector EJB instance You must create an instance of a Global Services connector EJB before you can invoke any connector methods to access a data source. To create a connector EJB instance, you first locate the connector by name and then call the connector create method. See Connector EJB naming conventions for connector naming conventions. The code in the following example shows how to create an instance of a connector with the base name of Adapter. 1 import javax.naming.initialcontext; 2 import javax.ejb.ejbobject; 3 import javax.ejb.ejbhome; 4 import javax.rmi.portableremoteobject; 5 import com.teamcenter.globalservices.connection.connectionboxhome; 6 import com.teamcenter.globalservices.connection.connectionbox; 7 import org.apache.log4j.logger; 8 9 import com.teamcenter.globalservices.exception.globalservicescommunicationexception;? 10 // Class, function definitions, etc. 11 String connectorname = "jndi-name"; Logger log = new Logger("class-name"); 12 try { 13 Properties props = System.getProperties(); 14 InitialContext ctx = new InitialContext(props); 15 ConnectionBoxHome home = (ConnectionBoxHome) PortableRemoteObject.narrow(ctx, ConnectionBoxHome.class); 16 ConnectionBox adapter = home.create(connectorname); } 17 catch (NamingException e) { // Thrown if lookup() fails 18 GlobalServicesCommunicationException ice= new 19 GlobalServicesCommnunicationException(TextBundleIDs.GS_EXCEPTION_TAG, 20 e.getmessage()); 21 log.fatal(ice.gettrackingcode() + " " + ice.getmessage(), ice); PLM00091 J Global Services Customization Guide 2-9

30 Chapter 2 Creating data source connectors 22 ice.initicause(e); 23 throw ice; } 24 catch (CreateException e) { // Thrown if create() fails 25 GlobalServicesCommunicationException ice= new 26 GlobalServicesCommunicationException(TextBundleIDs.GS_EXCEPTION_TAG, 27 TextBundleIDs.GS_EXCEPTION_TAG, e.getmessage()); 28 log.fatal(ice.gettrackingcode() + " " + ice.getmessage(), ice); 29 ice.initicause(e); 30 throw ace; } 31 catch (RemoteException e) { // Thrown if create() has general remote interface failure 32 GlobalServicesCommunicationException ice= new 33 GlobalServicesCommnunicationException(TextBundleIDs.GS_EXCEPTION_TAG, 34 e.getmessage()); 35 log.fatal(ice.gettrackingcode() + " " + ice.getmessage(), ice); 36 ice.initicause(e); 37 throw ice; } The following table describes the example code s function: Line numbers Description 1 4 Imports the standard Java naming and EJB classes required to find and create an instance of a connector EJB. 5 6 Imports the home and remote interfaces associated with the connector EJB. 7 9 Imports classes required to support exception handling and logging. 10 Provides class, function, variable, and other definitions required to make this a complete Java class Catches exceptions that might occur when attempting to create the instance. The try block is required to catch the possible exceptions thrown by the lookup and create methods Establishes an initial naming context for the connector instance. Uses the narrow method to return an interface of the appropriate type that is used to create an instance of the connector. 16 Uses the connector home interface create method to create an instance of the Global Services connector EJB. The data source name passed must match the name of a file with an.xml extension in the data source configuration directory Catches any of three exceptions that can be generated by the try block. The NamingException error is thrown by the lookup function if the connector name cannot be located. The CreateException error occurs if the security information of the user-id cannot be found, or if the link to the data source cannot be established. The RemoteException error occurs if there is a general remote communication failure. For each exception, a GlobalServicesException object is created that displays an informative message to the user. The exception is also logged to the appropriate file. For more information on exception handling, see Exception and message handling Global Services Customization Guide PLM00091 J

31 Creating data source connectors Establishing a data source link After creating a connector instance, you must establish a link to the data source before information can be requested from or sent to the data source. You establish the link using the connector connect method, along with the proper security information. The following code fragment is part of a method definition for a class that requires a link to a connector data source: //Data source link method 1 ConnectionBox adapter; Create an instance of a connector try { 6 adapter.connect(userid, null); } 7 catch (GlobalServicesException ae) { 8 // Let GlobalServicesException pass up to the UI level 9 throw ae; } 10 catch (Exception e) { Create and log an GlobalServicesDataSrcCommunicationException } The following table describes the example code s function: Line numbers Description 1 4 Defines the remote interface object. The ellipses indicate lines that create an adapter connector instance. 5 9 Catches the possible exceptions thrown by the adapter s connect method. At a minimum, connector methods defined in the remote interface of the connector throw the RemoteException error. 6 Calls the connector connect method to establish a link to the data source. For example, assume userid contains the user ID used to log into the Global Services environment. In this case, the connect method does a lookup for the appropriate user ID and password for this connector based on the Global Services security model. 7 9 Catches any GlobalServicesException error detected when attempting to establish a connection. This code is invoked when the remote request cannot be satisfied and Global Services detected the condition. Catching and returning the Global Services exception avoids a second Global Services exception for an error in the general catch (Exception e) block. For more information on exception handling, see Exception and message handling. PLM00091 J Global Services Customization Guide 2-11

32 Chapter 2 Creating data source connectors Line numbers Description Catches any exception thrown that is caused by conditions beyond the control of Global Services. In this case, the connector does not contain specific error information, so the text associated with the exception itself is written to the appropriate log. For more information, see Logging non-global Services exceptions. Calling connector methods After you create a Global Services connector instance and establish a link to the data source, invoking the connector methods is essentially the same as calling the methods of any Java object. The following code fragment shows a sample connector method call: // Connector method call 1 ConnectionBox adapter; 2. 3 Establish link with the connector 4. 5 SerializableCollection results; 6 SerializableCollection attrs = new SerializableArrayList(); 7 attrs.add("attrname1"); 8 attrs.add("attrname2"); 9 try { 10 WhereClause whereclause=whereclausefactory.getwherecluase("id=123 ); 11 results=adapter.query("class", whereclause, attrs); } 12 catch (GlobalServicesException ae) { 13 // Let GlobalServicesException pass up to the UI level 14 throw ae; } 15 catch (Exception e) { Create and log an GlobalServicesDataSourceException 18. } The following table describes the sample code function: Line numbers Description 1 4 Defines the remote interface object. The ellipses indicate lines that set the adapter to an instance of a connector remote interface. 5 Defines the results vector. The query method returns a vector of DataObject instances. 6 8 Defines and initializes the select attribute vector. In this example, AttrName1 and AttrName2 are the requested attributes Catches possible exceptions thrown by the connector query method call. At a minimum, connector methods defined in the remote interface of the connector throw the RemoteException error Global Services Customization Guide PLM00091 J

33 Creating data source connectors Line numbers Description Calls the getwhereclause method of the WhereClauseFactory class and the connector query method to retrieve the requested attributes from an instance of the class class that has an ID of 123. For this example, ID is the name of a key attribute in the class class Catches any GlobalServicesException error detected. The GlobalServicesException object is passed up to the user interface level. This code is invoked when the remote request cannot be satisfied and Global Services detected the condition. For more information on exception handling, see Exception and message handling Catches any exception thrown that is caused by conditions beyond the control of Global Services. In this case, the connector does not contain specific error information, so the text associated with the exception itself is written to the appropriate log. For more information, see Logging non-global Services exceptions. Using the remote interface All Global Services connectors support a set of methods defined as the BOX interface. The ConnectionBox.java file defines the BOX interface. Every connector must support remote calls to each ConnectionBox method, but the connector is not required to provide full implementation of each method. Each ConnectionBox method has the potential of returning a RemoteException exception. A method returns this exception when the connector does not support the function defined by the called method. The ConnectionBox interface defines the following methods: Method compute connect delete execute expand getlocalwildcardinfo getoriginalwildcardinfo Description Returns a string that contains the result of a connector client request. You call this method to establish a connector to the data source. The connector client calls this method to delete information from a data source. The connector client invokes this method to call a specialized connector function. You use this method to extend the functionality of the connector beyond the basic BOX interface. The connector client calls this method to expand a relationship maintained by a data source. Returns the wildcard information for the connector. Returns the characters that are string and positional wildcard attribute values defined in the connector configuration file. PLM00091 J Global Services Customization Guide 2-13

34 Chapter 2 Creating data source connectors Method insert query update Description The connector client calls this method to add a new object to the data source The connector client calls this method to requests information from the data source. The connector client calls this method to modify existing information in a data source. For more information, see the online class documentation (Global Services Javadoc) for the ConnectionBox class in the com.teamcenter.globalservices.connection package available from the Global Services Developer Info link. Connector life cycle Global Services connectors are stateful session beans and, therefore, have a well-defined life cycle. A connector is instantiated when the connector home interface calls the connector create method. After a connector instance is successfully created, a link must be established with the data source connector using the connect method. The caller s link to the data source connector is through the remote interface instance returned by the create function. The connector caller should retain the remote interface returned by the create method for the life of the user s session. Connectors, wherever possible, should make use of connector pooling to maintain fast, reliable, and efficient links to data sources. Connector instances, like any stateful session EJB, may be passivated if they are idle and system resources are scarce. The passivation process disassociates the connector instance information from the actual EJB object. This frees the associated resources for system reuse. All nontransient variables defined for the connector are automatically serialized by the container and restored when the connector is activated. However, the connector itself is responsible for disconnecting and reconnecting to the data source when the ejbpassivate and ejbactivate methods are invoked by the container. When connector pooling is not available, the data source link remains open for the lifetime of the connector. Connectors are subject to normal data source connect timeouts, but, should a timeout occur, the connector should attempt to reestablish the link during the next method access. You must call the remove method to end the life cycle of the connector cleanly. The remove method allows the connector to return all acquired resources, such as the data source link, to the system, and allows the system to reacquire the connector session bean resources. The remove method is invoked in the same fashion as the other connector methods. Extending Global Services connectors Global Services provides several connectors that extend the standard connector box interface. These connectors use the execute method to provide data source-specific functionality Global Services Customization Guide PLM00091 J

35 Creating data source connectors JDBC connector The JDBC connector provides the following connector extension through the execute method: SQL_EXTENSION Submits an SQL statement to the JDBC data source. Returns null. For more information about the JDBC extension methods, see the online class (com.teamcenter.globalservices.connection.jdbc.jdbcbox) documentation (Global Services Javadoc) available from the Global Services Developer Info link. Extending JDBC connectors JDBCBoxIf needed, you can extend the JDBC connector to provide additional data source-specific functionality. An extended connector is created in a similar manner to a custom connector to a new data source. You can use the existing home and remote interfaces (ConnectionBoxHome and ConnectionBox or JDBCBoxHome and JDBCBox) with the extended JDBCBoxBean class or you can extend them to expose methods used outside the Global Services framework. The following example shows the code required to create an extension to the JDBC connector. This example adds a metadata method to return the database vender name and version to the caller. Note The JDBCExtensionBoxBean class is not required unless you want to expose additional functionality so it can be called directly. Finally, you must implement the extended functionality in a bean class that extends the JDBCBoxBean class: /* bcprt This software and related documentation are proprietary to UGS Corp. COPYRIGHT 2005 UGS CORP. ALL RIGHTS RESERVED ecprt */ package example.jdbcext; import com.teamcenter._globalservices.exception.testglobalservicesexception; import com.teamcenter.globalservices.connection.connectionboximplementor; import com.teamcenter.globalservices.connection.connectorextension; import com.teamcenter.globalservices.connection.jdbc.jdbcboximpl; import com.teamcenter.globalservices.data.serializablearraylist; import com.teamcenter.globalservices.data.serializablelist; import com.teamcenter.globalservices.exception.globalservicesexception; import com.teamcenter.globalservices.log.loggerfactory; import com.teamcenter.globalservices.security.credentials; import java.io.serializable; import java.sql.connection; import java.sql.databasemetadata; import java.sql.sqlexception; import javax.ejb.createexception; /** * This is the implementation of an extended functionality of the JDBC connector. */ public class JDBCExtensionBoxBean extends com.teamcenter.globalservices.connection.jdbc.jdbcboxbean { private static com.teamcenter.globalservices.log.logger log_ = null; /** * This is a connector extension that executes an sql statement. * When executed it takes the following argument: * <pre> * (String) The SQL statement to execute. * and returns (null). */ public static final ConnectorExtension META_DATA_EXTENSION = new ConnectorExtension("metadata", 0) { PLM00091 J Global Services Customization Guide 2-15

36 Chapter 2 Creating data source connectors public Serializable execute(string bodname, ConnectionBoxImplementor connboximpl, SerializableList<?> args) throws GlobalServicesException { // Get the JDBC connector Connection con = ((JDBCBoxImpl)connBoxImpl).getConnection(); }; } // Get the connector MetaData try { DatabaseMetaData dmd = con.getmetadata(); log_.debug("method: Database=" + dmd.getdatabaseproductname() + " Version: " + dmd.getdatabaseproductversion()); SerializableList<String> results = new SerializableArrayList<String>(2); results.add(dmd.getdatabaseproductname()); results.add(dmd.getdatabaseproductversion()); return results; } catch (SQLException e) { throw new TestGlobalServicesException(e.getMessage()); } /** * Creates the bean. This method corresponds to the <code>create</code> method in the home * interface. It retrieves all EJB environmental properties that are configured in the * application server. */ public void ejbcreate(string configname, Credentials credentials) throws GlobalServicesException, CreateException { if (log_ == null) { log_ = LoggerFactory.getLogger(JDBCExtensionBoxBean.class); } super.ejbcreate(configname, credentials); getconnectionimpl().getconnectorextensionmap().put(meta_data_extension.getextensionname(), META_DATA_EXTENSION); } /** * Restores a passivated EJB. */ public void ejbactivate() { if (log_ == null) { log_ = LoggerFactory.getLogger(JDBCExtensionBoxBean.class); } super.ejbactivate(); getconnectionimpl().getconnectorextensionmap().put(meta_data_extension.getextensionname(), META_DATA_EXTENSION); } } /** * Add support for the execute method "meta" that returns the JDBC connection s product name * and version. */ public java.io.serializable execute(string name, String method, SerializableList<?> args) throws GlobalServicesException { log_.debug("method: execute(name=" + name + ") method=" + method); return super.execute(name, method, args); } The only code required is ConnectorExtension META_DATA_EXTENSION. This is made available to the execute(objectname, methodname, arguments) method by adding it to the connector extension map in the ejbcreate and ejbactivate methods. All other connector functionality is inherited from the JDBC parent class. The following are the key extension concepts: The execute method is not necessary as it only adds a debugging call. If it is not present, the functionality is the same (except for the debugging). The parent execute method (ConnectionBoxImpl) checks the methodname value against the connector extension map (getconnectorextensionmap) and if the extension is found, executes it. Registering the extension in the ejbcreate and ejbactivate methods makes it available Global Services Customization Guide PLM00091 J

37 Creating data source connectors The ConnectorExtension META_DATA_EXTENSION code obtains the JDBC connection established by the JDBCBoxImpl class. Performs the extension method processing and returns the results in a SerializableList<String> object. As noted in the JDBC extension example, the parent classes provide the bulk of the connector implementation including establishing a connection to the data source. To efficiently and effectively extend an existing connector, the extension class must have access to the connector-related objects. The JDBC connector class provides an accessor method to obtain the connector information. The following is the JDBCBoxImpl connector-related method: getconnection Returns the JDBC connection object to the data source. Teamcenter Enterprise connector The standard Teamcenter Enterprise connector extends the standard connector box interface. It uses the execute method to provide connector-specific functionality. It also provides several handlers that are specifically designed to use this extended connector functionality. Extending the Teamcenter Enterprise connector To create an extended connector, you must create an EJB home interface, a remote interface, and an implementation class. This is similar to creating a connector to a new data source as described in the. You add functionality by adding an extension method that is used with the execute method provided with all connectors. Each connector provides standard extension methods. The extension methods provided through the TcEntBoxBean class execute method are listed in the following table. After you create your extended connector, you must add it to the Global Services application. For general information on customizing Global Services and for the procedure for adding your custom components to the Global Services application, see Deploy a custom connector. In addition, the getexecutemethods method returns a vector of strings that list the methods implemented in the execute method.for more information about using the execute method extensions and the getexecutemethods method see the online Global Services Javadoc com.teamcenter.globalservices.connection.tcent package TcEntBoxBean class documentation available from the Global Services Developer Info link. For information about Teamcenter Enterprise functions, see the Teamcenter Enterprise manual set. Method acknowledgeworkitem approveworkitem bomextract bomfiledownload Description Acknowledges receipt of a distributed work item. Approves the assigned work item. Extracts a PLM XML formatted BOM from Teamcenter Enterprise. Downloads a BOM file from Teamcenter Enterprise. PLM00091 J Global Services Customization Guide 2-17

38 Chapter 2 Creating data source connectors Method bomfileupload bomload checkin checkout claimworkitem createrelation deleterelation download getclassnames getconnectioninfo getdbscope getworkflows getworklist listownerdirnames listvaults notokworkitem okworkitem rejectworkitem reviseitem routeworkitem setdbscope signoffworkitem submitworkitem Description Uploads a BOM file to Teamcenter Enterprise. Loads a PLM XML formatted BOM file to Teamcenter Enterprise. Performs an upload method and then a checkin method using files on the server. Returns a SerializableList instance of file objects identifying the checked-out file objects. Claims the work assignment and the associated work item. Creates a relation between two existing Teamcenter Enterprise objects. Deletes an existing Teamcenter Enterprise relation. Returns a file object identifying the location of the downloaded file item. Returns a list of class names for objects available to the requesting user. Returns a hashmap containing connection information from the connection object. Returns the database scope of the current user s session. Returns a SerializableList instance of the valid life cycles that the input work item can be submitted to. Returns a SerializableList instance of work assignments and related work items assigned to the current user. Returns a SerializableList instance of directory names available with the identified vault. Returns a SerializableList instance of strings containing vaults available to the requesting user. Disapproves the assigned work item. Approves the assigned work item. Rejects the reviewed work item. Makes a revision of the input business item. Routes the assigned work item. Sets the database scope of the current user s session. Signs off the assigned work item as Complete or NotComplete. Submits a work item to a workflow Global Services Customization Guide PLM00091 J

39 Creating data source connectors Method updaterelation upload Description Updates an existing Teamcenter Enterprise relation. Performs an upload method and an initial checkin method from a native file on the server. The following steps create an extension to the connector: 1. You define a home interface for the extended connector. 2. The extended connector remote interface extends the TcEntBox remote interface. Note No new method definitions are required unless you want to expose the additional functionality so it can be called directly. 3. You implement the extended functionality in a bean class that extends the TcEntBoxBean class. The only connector code required is the new implementation of the execute method to provide the new method functionality. All other connector functionality is inherited from the parent class. The new code provides the following key elements : 1. Examines the passed method name to determine if it is a custom execute method. 2. If the passed method is not a custom extension method, it calls the parent implementation of the execute method to perform any existing extension method. 3. If the passed method is a custom extension, obtains the existing connector established by the parent class implementation. Performs the extension method processing and returns the results in a vector. // Extension method import com.teamcenter.globalservices.connection.tcent.tcentboxbean; import com.teamcenter.globalservices.data.serializablelist; import com.teamcenter.globalservices.data.serializablearraylist; // other import statements as required public class TcEntBoxExtBean extends TcEntBoxBean { public Serializable execute(string name, String method, SerializableList args) throws GlobalServicesException { // results are returned in a vector. SerializableArrayList results = null; log.debug("method: execute(name=" + name +") method=" + method); // Check for all new extension methods first if (method.equals ("extname")) { // add the custom extension code here } else // If the method was not recognized, call the superclass { // to process the standard extensions results = super.execute( name, method, args); } return results; PLM00091 J Global Services Customization Guide 2-19

40 Chapter 2 Creating data source connectors } } The parent classes provide the bulk of the connector implementation including establishing a connection to the data source. To efficiently and effectively extend an existing connector, you must give your extension class access to the connector-related objects. The connector classes provide access methods to obtain the connector information. For more information about using the execute method extensions, see the online Global Services Javadoc TcEntBoxBean class documentation available from the Global Services Developer Info link. Call this extension method through a custom reactor EJB, action handler, or JavaServer Pages (JSP). The following code is an example of a custom handler for an execute extension method. // Custom execute method handler /** * Given a business object name, this action component creates a client and * executesthe "extnam" extension method on the connector for that business * object. * * <pre> * * Required input arguments: * "Object": A String containing he name of the business object * * Output arguments: * "result": A Serializable object returned from the invocation of the * "extnam" extension method * "message": An XML error string if an error occurs * * </pre> */ public class ExtActionComponent extends AbstractExceptionHandlerActionComponent { protected static final String OBJECT_REQUEST_KEY = "Object"; //req. input protected static final String RESULT_REQUEST_KEY = "result"; //output public Option handleactionimpl(actioncontext ctx, Arguments args) throws RequestManagerException, GlobalServicesException { String boname = (String) getreqargval(object_request_key, args); BOSClient client = BOSClientService.getClient(ctx, args); // create list for arguments SerializableList extargs = new SerializableArrayList(); // The extargs list should be populated with appropriate arguments // call client execute with extension method Serializable res = client.execute(boname, "extnam", extargs); args.setobject(result_request_key, res); return ctx.getoptionset().getoption(action_success); } } To use your custom action handler or JSP, provide a link element in the business object definition that contains the response chain or JSP Uniform Resource Locator (URL) with appropriate parameters as the href attribute value. For more information about business object definition and handlers, see the Global Services Configuration Guide and Customizing the user interface. The following are the TcEntBoxBean specific methods: 2-20 Global Services Customization Guide PLM00091 J

41 Creating data source connectors createunmanagedobject Registers a local unmanaged object in Teamcenter Enterprise using the target file name for the file to upload. The file location is unimportant because the file contents are streamed to Teamcenter Enterprise. getlogincontext Returns the COM.metaphasetech.util.LoginContext information associated with the connector. gettaskcontext Returns the COM.metaphasetech.tfw.TaskContext information associated with the connector. getmetaphaseobj Returns a Teamcenter Enterprise object that matches the specified generic object. Using Teamcenter Enterprise specific action handlers Global Services provides several action handlers for use with the Teamcenter Enterprise connector. These action handlers provide functionality that is required by most Teamcenter Enterprise users. Links ent-checkin-form enterprise-download ent-upload-form ent-upload-form2 Description Displays the form the user fills in to identify a file for checking in to Teamcenter Enterprise. The file must be one that was previously checked out. When the user submits the selection, it is forwarded to enterprise-upload handler, which executes the actual checkin. Downloads a file from Teamcenter Enterprise and streams it to the user. If necessary, this action handler checks the file out of a vault before downloading it. The file is downloaded in two steps: first, the connector downloads the file to a staging area at the server s site; second, the file is streamed to the handler caller. After the file is successfully transferred, the handler deletes the file from the staging area. Displays the first out of two forms used to upload a file to Teamcenter Enterprise. This form collects information about class name and vault to upload the file to. When the user submits the choices, they are forwarded to the second form (ent-upload-form2). Displays the form that allows a user to select the vault location and enter the path to the file, or browse to the file, they want to upload to enterprise. This is the final form displayed to the user prior to uploading the file through the enterprise-upload handler. PLM00091 J Global Services Customization Guide 2-21

42 Chapter 2 Creating data source connectors Links enterprise-upload Description Uploads files to the Global Services server. This handler executes an upload or checkin to an Teamcenter Enterprise data source using a streaming protocol. The following information describes how a user can use the connector-specific handlers provided with the connector to perform common operations. You can extend the basic functionality to provide a custom interface for your users. These operations are based on using the standard Teamcenter Enterprise connector and the sample business objects provided with the connector. For information about using the standard Global Services handlers, see Generic Global Services action components and response handlers. Uploading an object Users can upload objects to Teamcenter Enterprise using the standard Teamcenter Enterprise-specific handlers. An upload requires that the object be checked in to a vault. An object must be identified and the associated class and vault location obtained before it can be uploaded. The upload form handler presents the a form to the user as the first of a series that collects the required information: This provides a selection list of object classes that are available in your Teamcenter Enterprise installation. The getclassnames extension of the connector execute method is used to populate the list. The form also contains the user s vault or a list of vaults to choose from. Your users obtain a list of available vault locations to choose from by clicking the Obtain Vault Locations button. After an object type, vault, and vault location are selected, the user enters the complete path and file name in the File to upload field. If the path is not known, the user clicks the Browse button and Global Services provides a standard Open dialog box that users can use to select the file. Once the file is selected, clicking the Upload button transmits the file to Teamcenter Enterprise and checks it in to the designated location. Checking in an object An object that has been checked out from Teamcenter Enterprise can be checked in using the Global Services checkin form handler. Because the item must have been previously checked in, the user does not have to identify the object type, vault, or vault location as is required when initially uploading a file to Teamcenter Enterprise. The checkin form handler provides a field where the user enters the complete path and file name of the file to be checked in. If the path is not known, the user clicks the Browse button and Global Services provides a standard Open dialog box that users can use to select the file. Once the file is selected, clicking the Checkin button sends an HTTP request to the upload handler with the appropriate information. The upload handler transmits the file to Teamcenter Enterprise and checks it in to the designated location Global Services Customization Guide PLM00091 J

43 Creating data source connectors Downloading an object The download handler is used to both download and check out a file. A file in Teamcenter Enterprise can be copied without checking it out. If a download only is executed, the file is not checked out, but Global Services simply streams the file to the user. If you want to check out a file, the file is streamed to the user and the checkout action is performed on the file. The download handler requires a unique object ID (OBID) attribute in order to download or check out a file. Because the OBID is required, the download handler is usually accessed from a link provided on an object returned in a query. A checked-out object cannot be downloaded; therefore, the links provided on checked-out objects have the CheckedOut attribute set to False. The download handler copies the file to a staging directory on the Web server and then streams the file to the user s browser. The handler provides the MIME type for the file so that the browser can display it properly. SOA connector The Global Services SOA connector provides the standard connector methods through the services-oriented architecture (SOA) supported by Teamcenter. This consists of edit, query, update, insert, and delete as a minimum. You can use this connector to connect to Teamcenter 2007 and later versions, and it is required for Data Exchange. If you expose methods outside of the Global Services framework, a best practice is to use the ConnectionBoxBean class DestroyingCommand or VoidDestroyingCommand method, for example: public class MyTeamcenterSOABoxExtBean extends TeamcenterSOABoxBean { public DataObject getdata(string objectname) throws GlobalServicesException { return (DataObject) new DestroyingCommand() { public Serializable exec() throws GlobalServicesException { // do stuff return dataobject; } }.execute(); } } // more of the same Another best practice is for your client to make calls like: execute( TcSOAItem, TeamcenterSOABoxImpl.IMPORT_OBJECTS_EXTENSION, argumentlist) This is better than: execute( TcSOAItem, importobjects, argumentlist) In the first call, the second argument is checked by the compiler, whereas the string in the second call could be misspelled. The second call also adds overhead for mapping the name to the extension. For more information about the available SOA connector extension, see the online class (com.teamcenter.globalservices.connection.teamcenter) documentation (Global Services Javadoc) available from the Global Services Developer Info link. PLM00091 J Global Services Customization Guide 2-23

44 Chapter 2 Creating data source connectors For information about adding Teamcenter services, see the Business Modeler IDE Guide. Deploy a custom connector The two categories of custom connectors include connectors that extend standard connectors and connectors that do not extend standard connectors. Connectors that extend standard connectors are referred to as extended custom connectors. Connectors that do not extend standard connectors are referred to as independent custom connectors. The following setup and deployment steps describe how to deploy a custom connector. For more detailed information about this process, see the Installation on UNIX and Linux Servers Guide or Installation on Windows Servers Guide. You can obtain these guides from the Global Technical Access (GTAC) Web site at the following URL: 1. Create a home directory for the thin client components on your server customization host, then copy installation files from the software distribution image to this directory. 2. Create a customization directory structure for the files for your customization. 3. Create one or more installable component descriptor (ICD) files. The Web Application Manager uses information in ICD files to install your customization. For information about ICD files, see Developing your connector ICD file. 4. Run the Web Application Manager. This sets up application map and system preferences files for your customization. 5. Develop your customization. This involves writing code, compiling code, and developing archive files. 6. Iterate step 5 as necessary. 7. Package your customization by creating installable image (.jar) files. 8. Add entries to the ICD files you created in step Package your ICD files. 10. Run the Web Application Manager to install your customization. Developing your connector ICD file To extend an existing connector, ensure all files for the existing connector are included in the application and that the connector has access to the files in its classpath. Standard files can be included for use by the connector in two ways: 2-24 Global Services Customization Guide PLM00091 J

45 Creating data source connectors Specify in the ICD file that the connector is dependant on a standard connector. This ensures that the standard connector is installed when the connector is installed. Include the standard connector install image files in the connector ICD file. Use this method when you do not want the connector to be dependant on the standard connector. To access the standard connector classes, the connector MANIFEST.MF classpath must include the standard Java archive (JAR) files. Be sure to include connector nameejbs.jar with the connector classpath in the new connector classpath. If the connector requires libraries from the Enterprise Information System (EIS) but is not dependant on installing a standard base connector, you must include the EIS API JAR file in the application, using a COPYFILE tag. Following is a sample ICD file for a standalone custom connector: [NAME} Teamcenter GlobalServices My Custom MTI Connector [VERSION] [FILES] ugs_globalservices_tcent_connector my_custom_mti_connector [STAGING TYPE] EAR [PREREQUISITE_SOLUTIONS ugs_globalservices: [SOLUTION] Y [APPLICATION_PARAMS] { [EJB_FILES] ejb/my_mti_connectorejbs.jar } [COPYFILE] { [FROM] mti.jar [TO] lib } For information about ICD files and their contents, see Installable component descriptor (ICD) files. PLM00091 J Global Services Customization Guide 2-25

46

47 Chapter 3 Creating initiators Creating initiators Understanding initiators Implementing an initiator Initiator class InitiatorDialog class InitiatorMessage class Initiator command line options JMS queue message delivery Global Services message XML elements GlobalServicesMessage body param Initiator properties file PLM00091 J Global Services Customization Guide

48

49 Chapter 3 Creating initiators Creating initiators A reference initiator implementation (Java source and documentation) is supplied with this release of Global Services and provides much of the information that you need to create initiators. The following is introductory and supplemental information for the reference initiator implementation included with Global Services. Understanding initiators An initiator is the component that is responsible for sending messages from data sources to the Global Services message server or a JMS queue. The messages are distributed to reactors that have registered as subscribers for the particular message. Initiators may be created for any type of source, such as a database, a legacy system, a product knowledge management system, or even a browser. Implementing an initiator The Global Services example initiator consists of the following six classes: Initiator InitiatorDialog (optional) InitiatorMessage SendMessage (optional, may be used for JMS delivery) SendMessageAsynch (optional, may be used for JMS delivery) SendMessageSynch (optional, may be used for JMS delivery) The staging-directory\webapp_root\example\initiator directory (staging-directory/webapp_root/example/initiator directory for UNIX) contains the Initiator.java, InitiatorDialog.java, InitiatorMessage.java, initiator.properties, SendMessage.java, SendMessageAsynch.java, and SendMessageSynch.java files. You can use these files to build a working initiator or as a starting point for defining your initiators. These classes provide a reference implementation for sending Global Services messages to the Global Services message server formatted as a URL or as an XML text message. PLM00091 J Global Services Customization Guide 3-1

50 Chapter 3 Creating initiators For platforms that support Java technology, the Initiator class can be used as provided. For initiating messages from other Java code, you can import the InitiatorMessage class code and use it without this application and its associated dialog. For platforms that do not support Java technology, the send method in the InitiatorMessage class contains the method code that provides a blueprint of what is expected in the URL that is sent to Global Services. In this case, the code (C, C++, and so on) must open a socket connection to the Global Services Web application and send the HTTP message as implemented in the send method. This class also contains the sendjms method that provides the blueprint of what is expected in a Global Services XML formatted message that is sent to a JMS queue. Note To compile a custom initiator based on the Global Services sample files, you must have the globalservicescore.jar file included in your CLASSPATH environment variable. Additionally, to run your custom initiator, you must have any JAR files required by the message server that your initiator communicates with in the CLASSPATH environment variable. Initiator class The Initiator class is an application (provides a main method) that accepts command line arguments that represent the content of the message to be sent to the Global Services message server or a JMS message queue. If the command line contains the action (-A option), the initiator assumes it is a noninteractive message and sends it directly to Global Services. If no action is specified, the initiator assumes it is an interactive message and presents the InitiatorDialog class to the user. All command line arguments provide initial values for the dialog. A properties file provides the configuration for JMS message delivery. If the security is enabled for JMS message delivery, you must provide a user ID and password as parameters. The parameters can be provided on the command line. These parameters are passed through the URL to the message server for authentication. A sample initiator.properties file is provided with the sample initiator and an example is shown in Initiator properties file. The file name of the properties file to use for JMS message configuration must be provided as a command line argument to the initiator. The interactive method provides an easy way to test and debug message configurations and is not intended to be used as a production tool. If a JMS message sent through the publish action handler cannot be delivered to the JMS queue, the publish action handler sends it directly to the Global Services message server. InitiatorDialog class The InitiatorDialog class provides an interactive swing-based dialog for sending messages. All fields represent parameters that are built into the URL that is passed to the publish action handler. The user ID and password provided in the corresponding dialog fields are passed through the URL to the publish action handler for authentication. If the publish action handler is not secured, it ignores the user ID and password parameters. The InitiatorDialog class is provided as a tool for testing and troubleshooting the messaging process. InitiatorMessage class The InitiatorMessage class represents one or more messages to be sent to the Global Services message server. This class contains methods for 3-2 Global Services Customization Guide PLM00091 J

51 Creating initiators setting and getting message parameters, and the send method for opening a connection to the Global Services message server and sending messages. The sendjms method provides asynchronous or synchronous message delivery to a JMS queue. You can import this class and use it independently within other Java development. You must use authentication to send messages through the action handler. This requires creating a custom Authenticator subclass that has hardcoded user ID and password values. See the sample InitiatorMessage.java file and sample utility PasswordAuthenticator.java file in the staging-directory\webapp_root\example\util directory (staging-directory/webapp_root/example/util directory for UNIX) for an example. Initiator command line options The following options can be specified on the call line (no spaces are allowed between the option and parameters). Option -[Aa] -[Bb] -[Cc] -[Ff] -[Gg] Parameter description Action; required by all noninteractive messages. Publish message through publish action handler (true false); all actions. Class; publish action only. Full path of XML file for XML text message; JMS delivery only. Message group ID (GID); JMS delivery only. -[Hh] -[Ii] For additional information, see JMS queue message delivery. Global Services host; all actions. Default value is localhost. User ID for security validation; JMS delivery when security.flag = true (see the sample initiator.properties file). -[Jj] Global Services port; all actions. Default value is 80. -[Kk] -[Mm] Keys (name=value,...); publish action only. Message ID; JMS delivery only. For additional information, see JMS queue message delivery. -N Action queue persistence (true false); assures message delivery when set to true; JMS delivery only. Default value is false. For additional information, see JMS queue message delivery. -n Number of messages to send (1-9999); asynchronous JMS delivery only. Default value is 1. -[Oo] Message originator; all actions. PLM00091 J Global Services Customization Guide 3-3

52 Chapter 3 Creating initiators Option -[Pp] -[Qq] Parameter description Properties file containing configuration information; JMS delivery only. Response queue persistence (true false) assures message response when set to true; JMS delivery only. Default value is false. -[Rr] For additional information, see JMS queue message delivery. Response required flag (true false); JMS delivery only. Default value is false. -s Publish action handler URL. Default value is context-root/controller/publish. -[Tt] -[Uu] -[Ww] -[Xx] -[Yy] Message type; publish action only. Secure Socket Layer (SSL) communications (true false). Determines whether the initiator communicates using HTTPS or HTTP protocol. Default value is false (HTTP). Password for security validation; JMS delivery when security.flag = true (see the sample initiator.properties file). Extra arguments (name=value,...); publish action only. Asynchronous message flag (true false); JMS delivery only. Default value is false. For additional information, see JMS queue message delivery. For example: Initiator -apublish -tupdate -cpart -kpartnumber=m100b01 -ltrue -hnt100 -j80 The following are the valid values for each option parameter: The only valid value for action is publish. This action sends the message to the subscribed reactors. The valid values for message type are coordinated between the initiator and the reactors. The class parameter value represents the class, table name, or logical entity that is responsible for initiating the publish action. The key value pair specifies the key attribute name and its value. This parameter can be a comma delimited list of several attributes in order to identify a particular object. For example: -Klname=Raymond,fname=Scott The originator is the message publisher. This value is used to identify the message originator in the message log and is not used for any other purpose. You can set the value to any string that you want. If the data source is capable 3-4 Global Services Customization Guide PLM00091 J

53 Creating initiators of sending multiple Global Services messages, you can use this parameter to identify each originator. For JMS delivery (-[Bb] option value is false), the -[Rr] option valid values are true or false. The logging valid values are true or false. The host value specifies the host name or IP address of the Web server running Global Services. The port value specifies the port number of the Web server running Global Services. The value for the -s option parameter sets the destination for the message. When the -[Bb] option value is true, the -[Gg], -[Mm], -N, -[Qq], and -[Rr] options are invalid and are ignored. Additionally, if the publish action handler is not configured for JMS delivery, the -[Yy] option is invalid and ignored. When the -[Bb] and -[Rr] option values are false (JMS delivery and no response required), the -[Qq] option is invalid and is ignored. When no response is required, the message cannot be persistent. To use the -[Uu] option, the Java secure socket extension (JSSE) JAR files must be in the classpath. The JSSE comprises the jcer.jar, jnet.jar, and jsse.jar files. Additionally, the administrator must configure the application server to accept HTTPS communications. When the -[Yy] option value is true (asynchronous message), messages are sent through the SendMessageAsynch interface in the following cases: when the -[Bb] option value is true and the publish action handler is configured for JMS delivery, or when the -[Bb] option value is false. The publish action handler or initiator sends the message to the action queue and if the message is successfully written to the queue, the SendMessageAsynch interface returns a passed message result. No message response is written to the response queue. When the -[Yy] option value is false (synchronous message), and the -[Bb] option value is false messages are sent through the SendMessageSynch interface. If the -[Bb] option is true, basic (non-jms) message delivery is used. JMS queue message delivery Global Services provides sample implementations for asynchronous and synchronous JMS message delivery. You can base your implementation on the sample interfaces or you can implement the initiator to communicate directly with the JMS queue. You must be familiar with the requirements of a JMS queue if you decide to access the queue directly. Global Services provides a document type definition (GlobalServicesMessage.dtd) that defines the XML elements and structure for a Global Services message published to a JMS action queue. DTD file is defined within the DTDHolder class. A call to this class from the command line writes all of the Global Services DTD files PLM00091 J Global Services Customization Guide 3-5

54 Chapter 3 Creating initiators to disk in the current directory. Your initiator must send JMS TextMessage objects that contain text conforming to this DTD to write directly to a JMS queue. Global Services expects the following header properties in JMS messages: GID ID String that identifies your initiator. Used to distinguish responses to your initiator from those destined for other initiators. String that uniquely identifies an individual message. Used to retrieve the response for a particular message from the response queue. RESPONSE Boolean that indicates whether your initiator requests a response. Set to true to request a response. RESP_PERSIST Boolean that indicates whether the response message is persistent (placed in a data store until delivered). Persistent responses remain in the response queue even after a queue restart. Set to true for a persistent response. When sending multiple messages to the action queue, the example initiator generates a unique ID for each message. The initiator generates the ID using a command line or dialog supplied string as a base value. This base value is appended with a numeric sequence number that starts at zero (0) and increments to create unique message IDs. When extracting messages from the response queue, an initiator must use a selector that matches the initiator GID (GID in the header of the messages that the initiator writes to the action queue). The selector is used to retrieve responses that have the same GID in the message header. This is not necessary when a separate queue set is created for each initiator within Global Services (each initiator writes to its own action queue and reads from its own response queue). The following sample code illustrates the use of a selector. The following listing shows a sample JMS action queue message. <!-- Sample action queue XML message --> <?xml version="1.0"?> <!DOCTYPE GlobalServicesMessage SYSTEM "GlobalServicesMessage.dtd"> <GlobalServicesMessage> <body> <param name="type" value="reload"/> <param name="class" value="application"/> <param name="silent" value="true"/> <param name="class" value="department"/> <param name="class.deptno" value="10"/> <param name="class.deptname" value="accounting"/> <param name="date" value="06/13/ :25:38"/> </body> </GlobalServicesMessage> The elements and their attributes are described in Global Services message XML elements. 3-6 Global Services Customization Guide PLM00091 J

55 Creating initiators The sample InitiatorMessage class retrieves specific messages from the group with the same GID when you supply a selector containing a message ID. The message ID selector can contain the % wildcard character, allowing you to select sets of messages with the same GID and similar message IDs. Global Services message XML elements The following is a reference for the GlobalServicesMessage.dtd file elements and attributes. The following elements are defined in the GlobalServicesMessage.dtd file: GlobalServicesMessage (required) body (required) param (at least one required) PLM00091 J Global Services Customization Guide 3-7

56 Chapter 3 Creating initiators GlobalServicesMessage PURPOSE SYNTAX ATTRIBUTES EXAMPLE Contains the input data for the Global Services message. This is the top-level element for a JMS action queue message. <GlobalServicesMessage> <body> <param />. </body> </GlobalServicesMessage> None. <GlobalServicesMessage> <body> <param name="type" value="reload"/> <param name="class" value="application"/> <param name="silent" value="true"/> <param name="class" value="department"/> <param name="class.deptno" value="10"/> <param name="class.deptname" value="accounting"/> <param name="date" value="06/13/ :25:38"/> </body> </GlobalServicesMessage> 3-8 Global Services Customization Guide PLM00091 J

57 Creating initiators body PURPOSE SYNTAX ATTRIBUTES EXAMPLE Contains the input parameters of the Global Services message. The body element must contain at least one input parameter. <body> <param />. </body> None. <body> <param name="type" value="reload"/> <param name="class" value="application"/> <param name="silent" value="true"/> <param name="class" value="department"/> <param name="class.deptno" value="10"/> <param name="class.deptname" value="accounting"/> <param name="date" value="06/13/ :25:38"/> </body> PLM00091 J Global Services Customization Guide 3-9

58 Chapter 3 Creating initiators param PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the name-value pair mapping associated with the Global Services message. At least one name-value pair is required in a Global Services message. <param name="attribute-name" value="attribute-value /> name Specifies the name of an attribute in the Global Services message. This attribute is required. value Specifies the value associated with the named attribute. This attribute is required. <param name="type" value="reload"/> <param name="class" value="application"/> <param name="silent" value="true"/> <param name="class" value="department"/> <param name="class.deptno" value="10"/> <param name="class.deptname" value="accounting"/> <param name="date" value="06/13/ :25:38"/> Initiator properties file The properties in the initiator.properties file configure several aspects of a Global Services JMS queue. A sample initiator.properties file is located in the staging-directory\webapp_root\example\initiator directory (staging-directory/webapp_root/example/initiator directory for UNIX), and the properties are set to values for using JMS queues registered in JNDI. The file also contains values for using SonicMQ queues or IBM MQSeries queues that are commented out. The action and response queue names are set to action and response, respectively, by default. You must specify valid settings in the properties file for the JMS message server that you are using. If the properties in this file are not valid for the JMS message server that Global Services is using, Global Services does not receive the messages sent by your initiator. For more information on these settings and what they mean, see the documentation for your JMS message server. Security for HTML transfers is established through user ID and password authentication. The initiator.properties file contains the initiator security settings. If the security flag is set to true, the user ID and password are used to connect to the JMS queue server. The user ID and password values are also set in the properties file. If the security flag is set to false, which is the default value, the user ID and password are ignored. The time period that the initiator waits for a response to synchronous JMS messages can also be set in this file Global Services Customization Guide PLM00091 J

59 Chapter 4 Creating reactors Creating reactors Understanding reactors Reactor architecture Reactor EJB naming conventions Defining reactors Defining the reactor home interface Defining the reactor remote interface Defining the reactor implementation class Implementing reactors Using reactors BOSClient class Implementing transfer and synchronize functionality Deploying a custom reactor PLM00091 J Global Services Customization Guide

60

61 Chapter 4 Creating reactors Creating reactors A Global Services reactor receives messages from the Global Services message server and converts the message content into data source context. The following information explains how reactors are used and what you need to know to create a reactor. It does not attempt to tell you how to write methods to communicate directly to a data source. Understanding reactors Reactors process information between the data source object format and the business object format. The reactor receives notification of an event in a message from the message server and determines what action is necessary by the data source. If additional data source information is required, the reactor retrieves the information. A reactor is written as a single, stateless Enterprise JavaBean (EJB). A reactor may need more functionality than the data source connector provides. In that case, the reactor needs to communicate directly with the data source. Reactor architecture A Global Services reactor is an EJB that is implemented through three separate Java classes as specified by the EJB standard. The three Java classes represent the reactor home interface, the remote interface, and bean implementation. The following figure shows the high-level components and naming conventions used when creating a reactor. For more detailed naming information, see Reactor EJB naming conventions. PLM00091 J Global Services Customization Guide 4-1

62 Chapter 4 Creating reactors EJB Standard Classes EJBHome EJBObject SessionBean Message Server Interface Extended by Extended by GlobalServicesListener Implemented by Extended by Reactor Base Classes Reactor Implemented by ReactorBean Extended by Extended by Reactor Specific Classes reactorhome reactor reactorbean The reactor home interface defines the functions that are used to create an instance of the reactor. The message server requires all reactors to have one specific create function. The reactor remote interface defines the public access methods that can be remotely called by a reactor user. These public methods include the EJB standard methods as defined by EJBObject, the common reactor methods defined by the GlobalServicesMessageListener interface and any reactor specific extensions The reactor bean implementation class contains the logic of the reactor. The ReactorBean interface provides implementations for all of the SessionBean defined methods. It also provides stub implementations of all the common reactor methods defined by the reactor interface. Global Services provides a message consumer interface definition (GlobalServicesMessageListener) and foundation class implementation of a generic Global Services reactor (ReactorBean). All reactors must be extensions of the ReactorBean class. The GlobalServicesMessage class provides a generalized mechanism for passing message information throughout the Global Services environment. Information associated with a message is stored as strings within the message object and is modeled as attribute name-value pairs. The message server passes the GlobalServicesMessage information to the reactor in the form of an GlobalServicesMessage object. Reactor EJB naming conventions A Global Services reactor is an implementation of a stateless EJB. The reactor interface and class names must follow EJB standards in order to ensure proper and error free deployment. The following naming conventions apply: Home interface Remote interface Implementation ReactorHome Reactor ReactorBean Reactor is the base name of the reactor that contains the description of the data source, system, or both, related to the reactor. 4-2 Global Services Customization Guide PLM00091 J

63 Creating reactors Defining reactors To define a reactor you must define the home interface, the remote interface, and the implementation class. The staging-directory\webapp_root\example\reactor directory (staging-directory/webapp_root/example/reactor directory for UNIX) contains the ExampleReactorHome.java (home interface), ExampleReactor.java (remote interface), and ExampleReactorBean.java (implementation class) files. You can use these files as a starting point for defining your reactor. Note To compile a custom reactor, you must have the globalservicescore.jar file included in your CLASSPATH environment variable. Defining the reactor home interface The reactor home interface is an extension of the EJBHome interface that defines life cycle operations and metadata for the reactor bean. The interface provides a client side API for creating and removing the reactor beans. You must define the common reactor create method with no arguments and the following signature: public interface ReactorHome extends javax.ejb.ejbhome { Reactor create() throws CreateException, RemoteException, GlobalServicesException; } Note The Global Services toolkit does not provide a base class for the reactor home interface. For correct deployment, the create method defined for the reactor home interface must return a class with the specific reactor remote interface name. If you define a generic create function in a ReactorHome interface that returns Reactor, it does not satisfy the EJB deployment requirements. Defining the reactor remote interface The reactor remote interface exposes the public methods that are remotely called by reactor clients, such as the message server. This interface defines the client side API for the reactor. Reactors are only required to provide the interface used by the message server, as defined by the GlobalServicesMessageListener interface. You can add additional method definitions to extend this interface. This interface defines the client side API to the reactor. Reactors are only required to provide the interface used by the message server as defined by the GlobalServicesMessageListener interface. However, you can extend the remote reactor interface by adding additional method definitions. The reactor remote interface is defined as follows: public interface Reactor extends Reactor { // Reactor extension methods defined here } Defining the reactor implementation class The reactor implementation class contains the code that performs the business logic associated with the data source. The reactor implementation class must extend the base ReactorBean class to function properly in the Global Services environment. However, your reactor class can override any of the methods defined PLM00091 J Global Services Customization Guide 4-3

64 Chapter 4 Creating reactors by the ReactorBean class provided the superclass method is still invoked. See Implementing reactors. Define the reactor implementation class as follows: public class ReactorBean extends ReactorBean { // Local variables and methods // Method overrides of ReactorBean methods // Extension methods defined in the reactor remote interface } Implementing reactors After you define the reactor, you implement the reactor to access a new data source type. To implement the reactor home interface you only need to define the interface as described in Defining the reactor home interface. This implementation is automatically provided as part of the EJB container system. In addition, many of the methods provide capabilities critical to proper functioning of the Global Services environment. Because some of these methods must be overridden in order to implement a functioning data source reactor, Siemens PLM Software recommends that you always invoke the ReactorBean implementation when overriding a function. Therefore, each reactor override method should follow this format. For the reactor remote interface, the ReactorBean class provides a basic implementation of the home create, SessionBean, and Reactor interfaces, as required by the EJB standard. Many of these methods provide capabilities critical for the proper functioning of the Global Services environment. Since you must override some of these methods in order to implement a functioning data source reactor, Siemens PLM Software recommends that the ReactorBean implementation always be invoked when overriding any of these functions. Override reactor methods as shown in the following example: public void reactormethod( type1 name1,..., typen namen) { super.reactormethod( name1,..., namen); // Reactor specific code } When you implement a reactor, the following ReactorBean methods are typically overridden: Create method ejbcreate Description Invoked when the reactor home create method is called by the message server. It is called only once during the EJB life cycle. The default implementation provides automated trace information and nothing else. You override this method to perform any one-time initialization such as establishing a data source connection. 4-4 Global Services Customization Guide PLM00091 J

65 Creating reactors Session bean interface method ejbremove Description Invoked only once during the EJB life cycle, before releasing the EJB instance. You should override this method to return any resource to the system that the EJB acquired, such as closing a link to the data source. The super class function should be called before executing the local implementation. Reactor interface methods Description onglobalservicesmessage You must override this method to provide the basic reactor functionality of processing GlobalServicesMessage information. This message returns a string that appears inside the details element tags of a messageresult formatted XML message. If a string is returned, the reactor is assumed to have successfully processed the message. If an exception is thrown, the reactor is assumed to have failed. When a GlobalServicesException object is thrown during an onglobalservicesmessage method call, the details element content for the ReactorResult element is set by the GlobalServicesException.setDataValue method. For example: GlobalServicesException.setDataValue("ReactorResult.details", somestring); The ReactorBean implementation also contains several data access methods. The following is used the retrieve local variables. Reactor data access method getsessioncontext Description Returns the session context for the reactor bean. The session context can be used to retrieve environment and other variables. You can retrieve the values of the environment variables at runtime using the following code within the reactor bean implementation: SessionContext sessionctx_ = getsessioncontext(); Properties env_ = sessionctx_.getenvironment(); String property_ = env_.getproperty("property-name"); Using reactors The Global Services reactor class provides a complete EJB default implementation for all required EJB methods. You are free to override or reuse the default implementations as necessary. Because Global Services reactors are stateless session beans, they have a well-defined life cycle. Reactors are instantiated by the message server to process a message for which the reactor is registered. Your reactor should not attempt to retain any information between message processing. The create PLM00091 J Global Services Customization Guide 4-5

66 Chapter 4 Creating reactors method is invoked by the message server to establish an instance of the reactor. The remove method is invoked by the message server to cleanly end the life cycle of the reactor. The remove method allows the reactor to return all acquired resources, such as the data source connector, to the system and allows the system to reacquire the reactors session bean resources. All required resources must be established during the create method call and be released during the remove method call. BOSClient class The BOSClient class is a Java convenience class that hides the details of linking to connectors and calling the individual connector methods. The purpose of this class is to supply the interface from a client (reactor or Java application) to the business object server of Global Services or, if required, directly to a data source connector. For more information about the BOSClient class, see Using the convenience classes. Implementing transfer and synchronize functionality Global Services EPSync reactor components provide a generic mechanism to transfer and synchronize information and data between systems connected through Global Services connectors. EPSync functionality provides the following functions: Supports any connected system, such as Microsoft Excel and Access, Oracle database, and DB2 database. Provides bidirectional data transfer and synchronization. Allows you to define the target system in the publish message. Additionally, it allows the target system identifier to be a parameter on the publish message. Allows additional source object queries. No wildcards are allowed. It uses the WhereClause class and additionally allows you to pass an SQL where clause as a parameter on the publish message. This allows you to transfer many objects in a single request. Provides processing of structural hierarchy using parent and child classes. You can process a single level (parent only or immediate children only), two levels (parent and immediate children), or all levels (the entire hierarchical structure). Provides relation support with the capability to recreate the hierarchical structure on the target system, if supported by the target system. Allows access messages to be a configurable option and generates status messages for those systems that do not provide them. Standard EPSync functionality supports relationships only for the Teamcenter Enterprise connector. If you are using this functionality with other systems and do not need to handle relationships, you only need to edit some XML configuration files. This information is provided in the Global Services Configuration Guide. To support relationships with other connectors, you must ensure the expand method is implemented in the connector. 4-6 Global Services Customization Guide PLM00091 J

67 Creating reactors Deploying a custom reactor Because a reactor is an EJB, it is deployed in the same manner that a custom connector EJB is deployed. Use the same process to create an ICD file for your customization and to deploy your reactor described in Developing your connector ICD file and Deploy a custom connector. PLM00091 J Global Services Customization Guide 4-7

68

69 Chapter 5 Customizing the user interface Customizing the user interface Creating action components, JSP pages, and response chains Action components JSP pages Response chains Generic Global Services action components and response handlers Application map links JSP pages Building forms and tables Using links in the user interface BOS list, search form, and search links Compute and compute form links Delete and delete form links Expand link Insert and insert form links Update and update form link Using style sheets Presentation elements error.dtd aetitle class error text trace tracking type messageresult.dtd details MessageResult ReactorResult status result.dtd data function operation result PLM00091 J Global Services Customization Guide

70

71 Chapter 5 Customizing the user interface Customizing the user interface The Global Services presentation layer provides the user interface primarily through the standard Teamcenter Web tier framework, which includes application maps, action components, system preferences, and JSP pages. However, a few servlets and XSL style sheets are also used to provide error and status information. The goal of this information is not to provide complete documentation about the Web tier, but rather the unique ways that Global Services uses the Web tier. For complete information about standard Web tier framework and its components contact the Global Technical Access (GTAC) Web site at the following URL: Creating action components, JSP pages, and response chains Action components are your programming entry points. Action components are, together with JSP pages and response handlers, arranged into response chains to provide UI operations for the end user. When creating a new UI operation (that is, a link that can be invoked from a browser) you typically configure a new response chain that utilizes a mix of existing Global Services utility action components, one or more newly developed action components that are specific to your particular response chain, and finally a JSP or response handler that renders the visual feedback of the operation. Action components Action components perform most of the work in the UI framework. An action component is a Java class that represents a distinct task that typically includes interacting with the back end, performing simpler data processing, and making the result available to predecessors in the chain. Note that creating visual feedback is typically not an action component responsibility, as this is done using JSP pages or response handlers. To create a new action component, you can either create a class that implements the ActionComponent interface, or you can take advantage of various Global Services functionality, particularly a standardized exception handling model, by subclassing the AbstractExceptionHandlerActionComponent action component. The example/actionchain directory contains the GetBODActionComponent.java and UpdateBODActionComponent.java sample action components, the editform.jsp sample JSP page, and the example_app_map.xml sample application map that contains the response chains that bind it all together. You can use these files as a starting point for creating your own UI operations. PLM00091 J Global Services Customization Guide 5-1

72 Chapter 5 Customizing the user interface If you decide to create your action components by implementing the ActionComponent interface, you are creating a general action component that is not Global Services specific. If you extend the AbstractExceptionHandlerActionComponent action component, you must at a minimum implement the handleactionimpl method: protected abstract Option handleactionimpl(actioncontext action_context, Arguments component_arguments) throws Exception; The action_context argument is used for retrieving and setting general information to the context of the action. The component_arguments argument is used for retrieving parameters from the original HTTP request, retrieving variables created by action components that executed earlier in the response chain, and writing variables that were created during the execution of this action component. The AbstractExceptionHandlerActionComponent class (and its superclass, AbstractActionComponent) provides several features to be used by its subclasses. The getargval and getreqargval convenience methods are used to obtain optional and required variables respectively that were set by previous action components or by the original HTTP request. It also provides the standard ACTION_SUCCESS and ACTION_FALURE return value constants used by Global Services action components, convenience methods for generating XML error messages and parsing comma based strings, a member variable specifying the user locale, and so on. Subclasses of the AbstractExceptionHandlerActionComponent class can also take advantage of a standardized exception handling framework. Unless an action component needs to handle exceptions in a specific way, it can be left uncaught which causes the AbstractExceptionHandlerActionComponent action component to catch it and create an XML error message that can be used to render an error page for the user. A minimalist action component implementation could look like this: public MyActionComponent extends AbstractExceptionHandlerActionComponent { public Option handleactionimpl(actioncontext ctx, Arguments args) throws RequestManagerException, GlobalServicesException { String firstname = (String)getReqArgVal( firstname, args); String lastname = (String)getArgVal( lastname, args); String name = firstname + (lastname == null? : + lastname); args.setobject( fullname, name); return ctx.getoptionset().getoption(action_success); } } This implementation uses convenience methods to read the required first name and the optional last name from the args object (they may have been written by a preceding action component or by the original HTTP request itself), concatenates them and writes the result to the args object, making it available to action components, JSP pages, and response handlers further down the chain. Finally, it returns the standard ACTION_SUCCESS (= success ) option to indicate to the response chain that everything is working. If something goes wrong (for example, no value is defined for the firstname entry, causing the getreqargval entry to throw an exception), control is transferred to the AbstractExceptionHandlerActionComponent action component that writes an XML error message to the args object. 5-2 Global Services Customization Guide PLM00091 J

73 Customizing the user interface JSP pages JSP pages are used by the UI framework (as recommended by the J2EE blueprints) to render the results of previous action components into something that can be visually presented to the user. As such, JSP pages should not interact with the back end, contain business logic, or perform any processing of the data fed to them. The following example shows a minimalist JSP page (displaystring.jsp) that could be used together with the action component outlined previously: <% String data = (String)request.getAttribute("name");%> <html> <body> <%=data%> </body> </html> The action component writes its result data to a fullname object in the args object. The JSP page refers to this same result data as name. Using different aliases for a given object is possible because of the mapping capabilities of response chains, discussed next. Response chains Now that you know how to create action components and JSP pages for the framework, you can combine them into useful flows of control using a response chain. A response chain is the glue that binds together action components, JSP pages, response handlers, and so on to form a flow of control. A response chain can be invoked by an HTTP request, much like a servlet. Response chains are declared in an application map XML file. The concept of configurable response chains is both flexible and powerful, and this description only addresses how it is used by the Global Services UI. A simple Global Services response chain could look as follows: <page id="displaystringpage" path="/jsp/displaystring.jsp"/> <link id="example-link" response-chain="example_response_chain"/> <response-chain id=" example_response_chain"> <chain-options> <option id="success" advance="true"/> <option id="failure" response-chain="error_chain"/> </chain-options> <action-component id="myactioncomponent" handler="test.myactioncomponent"> <component-input id="firstname" source="christianname"/> <component-input id="lastname" source="familyname"/> <component-output id="fullname" destination="name"/> PLM00091 J Global Services Customization Guide 5-3

74 Chapter 5 Customizing the user interface <component-output id="message" destination="message"/> </action-component> <final-option page="displaystringpage"/> </response-chain> The response chain has the following features: The link tag binds a link (which can be invoked from a browser) to the response chain. The page tag declares a page so that it can be referenced from the response chains. The chain options declared at the response chain level apply to all action components in the chain. They specify what should happen next when an action component returns with a given option. Note that the response chain is set up so that if an action component returns failure, it aborts its execution and forwards the execution to the error_chain chain. The error_chain chain is a generic Global Services response chain that is declared in the default Global Services application map file. Although the MyActionComponent action component internally refers to its variables as firstname, lastname, and fullname, its declaration in the response chain defines other aliases for them (givenname, familyname, and name) that are used when referring to these variables from other entities within the response chain, or when invoking the response chain via the link. Although the MyActionComponent implementation only has one output variable, fullname, it is still necessary to declare a message output variable as well. This is true for all subclasses of the AbstractExceptionHandlerActionComponent class, since it writes an XML error string to the message variable in case an exception occurs. When the response chain has executed successfully, it forwards to the JSP page. To invoke this response chain, the proper URL syntax would be something like example-link?givenname=foo&familyname=lar. This produces the following response: <html> <body> Foo Lar </body> </html> Generic Global Services action components and response handlers The Global Services UI contains several generic action components that can be reused when configuring custom action chains. The most important ones are described in the following list. For more detailed information on their use and configuration, see the corresponding Javadoc. For examples on how they are actually used, see the ui_app_map.xml file. 5-4 Global Services Customization Guide PLM00091 J

75 Customizing the user interface XSLTransformActionComponent This action component is typically put at the end of response chains where a previous response chain has created XML output that needs to be rendered into HTML using a stylesheet. VerifyAdminRoleActionComponent This action component is typically put in the start of a response chain that only administrative users should be allowed to run. If the user does not have administrative privileges, it throws an exception that causes the response chain to be aborted and the error chain to run instead. RequestParamMapActionComponent The UI framework expects all input and output parameters to an action component to be declared in the response chain. This causes problems in cases where the number of parameters is not known until runtime. For instance, an HTTP request may contain the parameters name1=mike, name2=melissa, name3=maurice, namex=maria. The actual number of parameters may vary from call to call, and since there is no upper limit, it would be impossible to declare them in the response chain. This action component addresses this problem by accessing the original request object directly, thus bypassing the normal way of declaring each parameter explicitly in the response chain. BuildWhereFromDynaAttribsActionComponent Much interaction with the BOSClient client requires a WhereClause object that identifies what data sets to operate on. This action component is designed to be used in conjunction with the RequestParamMapActionComponent action component in order to create a WhereClause object based of a set of name-value pairs in the original request. GenericResponseHandler This response handler is typically used at the end of response chains that do not rely on JSP pages to render the result sent to the client. For example, it would be the response handler of choice for a response chain in which a previous action component has rendered an XML document or HTML document that should be sent to the client (such as the XSLTTransformActionComponent action component). FileDownloadResponseHandler This response handler is typically used by response chains whose output is a file to be downloaded to the client. Application map links Global Services provides application map links that route to response chains that allow you to perform a basic set of operations. You can create your own links to add additional functionality to your user interface. Global Services provides the links listed in the following table. You can find these links in the WEB-INF/teamcenter/globalservices/ui_app_map_xml.template file. PLM00091 J Global Services Customization Guide 5-5

76 Chapter 5 Customizing the user interface Link ID compute compute-form datastore-download datastore-remove datastore-upload delete delete-form eng-checkin eng-checkout eng-download-form eng-download-form2 eng-upload-form eng-upload-form2 Description Performs a MAX, MIN, AVG, SUM, or COUNT computation on an attribute for all the records of a business object. Displays the attributes of a business object. The user enters one of the SQL compute functions (MAX, MIN, AVG, SUM, or COUNT) for a single attribute. Calls compute when the user clicks the Continue button. Downloads a file from the datastore. Deletes a file from the datastore. Uploads a file from the datastore. Deletes a business object record. Displays a record the user has selected to delete. The display allows the user to verify the correct record is selected before it is deleted. Calls delete when the user clicks the Continue button. Checks in an object to Teamcenter engineering process management. Checks out an object from Teamcenter engineering process management. Displays a form that requests input parameters needed to download a file from Teamcenter engineering process management. The input parameters are obtained one at a time by performing queries to Teamcenter engineering process management. Calls eng-download-form2 when the user clicks the Continue button. Displays the second of two forms that request input parameters needed to download a file from Teamcenter engineering process management. This form also requests the file to be downloaded. Calls engineering-download when the user clicks the Continue button. Displays a form that requests input parameters needed to upload a file to Teamcenter engineering process management. The input parameters are obtained one at a time by performing queries to Teamcenter engineering process management. Calls eng-upload-form2 when the user clicks the Continue button. Displays the second of two forms that request input parameters needed to upload a file to Teamcenter engineering process management. This form also requests the file to be uploaded. Calls engineering-upload when the user clicks the Continue button. 5-6 Global Services Customization Guide PLM00091 J

77 Customizing the user interface Link ID engineering-download engineering-upload ent-checkin-form ent-upload-form ent-upload-form2 enterprise-download enterprise-upload expand insert insert-form list-bos search search-form update update-form Description Downloads a file from Teamcenter engineering process management using a staging protocol. Uploads a file to a Teamcenter engineering process management data source using a staging protocol. Displays a form requesting the file to be checked in to Teamcenter engineering process management. The file must have been previously checked out. Calls enterprise-upload when the user clicks the Continue button Displays a form that requests input parameters needed to upload a file to Teamcenter engineering process management. The input parameters are obtained one at a time by performing queries to Teamcenter engineering process management. Calls ent-upload-form2 when the user clicks the Continue button. Displays the second of two forms that request input parameters needed to upload a file to Teamcenter engineering process management. This form also requests the file to be uploaded. Calls enterprise-upload-form when the user clicks the Continue button. Downloads or checks out a file from Teamcenter engineering process management. Uploads or checks in a file to Teamcenter engineering process management. Expands relationships. Inserts business object record. Displays a record for inserting. The form provides fields for the user to supply the attribute values for the record and calls insert when the user clicks the Continue button. Lists all business objects in the business object server (BOS) that the user has authority to view. Searches for matching business object records and displays the results in a table. Displays the searchable attributes of a business object. The form provides fields for the user to supply searchable attribute values and calls search when the user clicks the Continue button. Updates business object record. Displays a record for updating. The form provides fields for the user to supply update information and calls update when the user clicks the Continue button. PLM00091 J Global Services Customization Guide 5-7

78 Chapter 5 Customizing the user interface Global Services provides the following links to perform administration and specialized functions in Global Services: Link ID msgserver-creatables msgserver-deletemsgs msgserver-republishmsg msgserver-republishreactor msgserver-reset msgserver-setlogging publish snoopsnoop-ejb Description Creates the database tables used by the message server. Deletes old messages from the database. Republishes the message to the supplied reactor, unless the message log indicates that the message already has been successfully published to that reactor. Extracts all messages out of the log that are associated with the given reactor and were not processed to completion, and republishes them to the given reactor. Resets the message server. Turns message server logging on or off. Publishes (sends) messages to the message server. The message is sent to the message server though RMI / IIOP or JMS depending on the configuration. Displays status of Global Services response chain links. Shows status as installed when the response chain link is properly installed. Displays status of Global Services Enterprise JavaBeans (EJBs). Shows status as installed when the EJB is properly installed. JSP pages When you click a button in the UI that invokes a link, the link invokes a JSP page called at the end of the response chain. The following table lists the standard JSP pages provided by Global Services. JSP name boslist.jsp computeform.jsp ConfigureDataStore.jsp deleteform.jsp fileuploadform.jsp Description Renders the HTML output for the list-bos link. Renders the HTML output for the compute-form link. Provides a Web interface for upload, download, and removal of datastore configuration objects. Renders the HTML output for the delete-form link. Renders the HTML output for the ent-checkin-form, ent-upload-form2, and eng-upload-form2 links. 5-8 Global Services Customization Guide PLM00091 J

79 Customizing the user interface JSP name index.jsp insertform.jsp loadform.jsp Login.jsp PortalBottom.jsp search.jsp searchform.jsp StatusPage.jsp topbanner.jsp updateform.jsp Description Semistatic JSP that renders the HTML frame structure of the UI. Renders the HTML output for the insert-form link. Renders the HTML output for the ent-upload-form, eng-upload-form, eng-download-form, and eng-download-form2 links. The logon page is displayed when any of the Global Services URLs is called by an unauthenticated user. This page is either a Security Services login page if Security Services is enabled, or the standard Global Services login page if Security Services is disabled. Semistatic JSP that renders the HTML displayed in the bottom frame. Renders the HTML output for the search and expand links. Renders the HTML output for the search-form link. Renders the HTML output used when a link is invoked with a parameter output that equals status. Semistatic JSP that renders the HTML displayed in the top frame. Renders the HTML output for the update-form link. Building forms and tables Global Services provides the FormBuilder and TableBuilder classes you can use to build forms and tables for use in your user interface. The FormBuilder class contains two buildform methods for building form objects that can be serialized into XML. The XML can be converted to HTML, or the form objects can be used directly by JSP pages for constructing forms. The version of the buildform method that takes a DataObject parameter is used to generate Update and Delete forms. The form object this method generates contains attribute names and values from the data object. The second version of the buildform method does not take a DataObject parameter and it is used to generate query and insert forms that do not have attribute names and values. The schema definition for the form object XML generated by the interface tostring method is shown in the following listing. <!-- Form schema --> <?xml version="1.0" encoding="utf-8"?> <!-- bcprt This software and related documentation are proprietary to UGS Corp. COPYRIGHT 2005 UGS CORP. ALL RIGHTS RESERVED ecprt --> <xs:schema xmlns:xs=" xmlns:jaxb=" xmlns:xjc=" xmlns:bod=" xmlns:conn=" xmlns:data=" xmlns:form=" PLM00091 J Global Services Customization Guide 5-9

80 Chapter 5 Customizing the user interface xmlns:util=" targetnamespace=" jaxb:extensionbindingprefixes="xjc" jaxb:version="1.0" elementformdefault="qualified"> <xs:import namespace=" schemalocation="business-object-definition.xsd"/> <xs:import namespace=" schemalocation="data.xsd"/> <xs:import namespace=" schemalocation="connection.xsd"/> <xs:import namespace=" schemalocation="util.xsd"/> <xs:element name="form"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.form.formimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="max-objects" type="xs:int"/> <xs:element name="bod-name" type="xs:string"/> <xs:element name="object-label" type="xs:string"/> <xs:element name="-url" type="xs:string"/> <xs:element name="-operation" type="xs:string"/> <xs:element name="record-id" type="xs:string" minoccurs="0"/> <xs:element ref="form:attribute-info" minoccurs="0" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="attributelist"/> </xs:appinfo> </xs:annotation> </xs:element> <xs:element ref="conn:wildcard-info" minoccurs="0"> <xs:annotation> <xs:appinfo> <jaxb:property name="wildcardinfoelem"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> </xs:complextype> </xs:element> The TableBuilder class contains two buildtable methods for building table objects that can be serialized into XML. The XML can be converted into HTML or the table object can be used directly by JSP pages for constructing tables. The version of the buildtable method that takes a list of BODs is used for generating the BOS list table object. The BOS list is a list of business object names with links to a URL, such as the search-form action handler for each business object. The second version of the buildtable method takes a BOD and a list of data objects and creates a table object that contains entries with a row for each of the DataObjects instances and a column for each of the attributes defined in the BOD. This table object is used to generate the output of the search action handler. The schema definition for the table object XML generated by the interface tostring method is shown the following listing. <!--Table schema --> <?xml version="1.0" encoding="utf-8"?> <!-- bcprt This software and related documentation are proprietary to UGS Corp. COPYRIGHT 2005 UGS CORP. ALL RIGHTS RESERVED ecprt --> <xs:schema xmlns:xs=" xmlns:jaxb=" xmlns:xjc=" xmlns:table=" targetnamespace=" jaxb:extensionbindingprefixes="xjc" jaxb:version="1.0" elementformdefault="qualified"> <xs:element name="table"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.table.tableimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="bod-name" type="xs:string"/> 5-10 Global Services Customization Guide PLM00091 J

81 Customizing the user interface <xs:element name="label" type="xs:string" minoccurs="0"/> <xs:element ref="table:row" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="rows"/> </xs:appinfo> </xs:annotation> </xs:element> <xs:element ref="table:link" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="links"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="row"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.table.rowimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element ref="table:attribute" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="attributes"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="attribute"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.table.attributeimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="name" type="xs:string"/> <!-- the value to display --> <xs:element name="display-value" type="xs:string" minoccurs="0"/> <xs:element name="color" type="xs:string" minoccurs="0"/> <xs:element ref="table:link" minoccurs="0" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="links"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="link"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.table.linkimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="label" type="xs:string"/> <xs:element name="href" </xs:sequence> </xs:complextype> </xs:element> type="xs:string"/> </xs:schema> <xs:element name="attribute-info"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.form. AttributeInfoImpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element ref="data:attribute-value"/> <xs:choice> <xs:element ref="bod:attribute"> <xs:annotation> <xs:appinfo> <jaxb:property name="staticattributedefinition"/> </xs:appinfo> </xs:annotation> </xs:element> <xs:element ref="bod:dynamic-attribute"> PLM00091 J Global Services Customization Guide 5-11

82 Chapter 5 Customizing the user interface <xs:annotation> <xs:appinfo> <jaxb:property name="dynamicattributedefinition"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:choice> <xs:element name="sort-priority" type="xs:int" minoccurs="0" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="sortprioritylist"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> </xs:complextype> </xs:element> <!-- - XML tag for an upload/download form. --> <xs:element name="load-form"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.form.loadformimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="bod-name" type="xs:string"/> <xs:element name="-url" type="xs:string"/> <xs:element name="-operation" type="xs:string"/> <xs:element name="display-name" type="xs:string"/> <xs:element name="button-title" type="xs:string" minoccurs="0" /> <xs:element ref="util:where-clause" minoccurs="0"> <xs:annotation> <xs:appinfo> <jaxb:property name="where"/> </xs:appinfo> </xs:annotation> </xs:element> <xs:element ref="form:entry" minoccurs="0" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="entrylist"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> </xs:complextype> </xs:element> <!-- - XML tag for an upload/download form. --> <xs:element name="entry"> <xs:annotation> <xs:appinfo> <jaxb:class implclass="com.teamcenter._globalservices.form.entryimpl"/> </xs:appinfo> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="display-name" type="xs:string"/> <xs:element ref="util:param" minoccurs="0" maxoccurs="unbounded"> <xs:annotation> <xs:appinfo> <jaxb:property name="parameters"/> </xs:appinfo> </xs:annotation> </xs:element> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required"/> </xs:complextype> </xs:element> </xs:schema> Using links in the user interface A user can use the standard links provided with Global Services to perform common operations. You can extend the basic functionality to provide a custom interface for your users. These operations are based on using the standard JDBC connection and the sample business objects provided with Global Services For more information on using the administration links, see the Global Services Configuration Guide Global Services Customization Guide PLM00091 J

83 Customizing the user interface BOS list, search form, and search links Although the search and BOS list link can be used independently, they are typically used in conjunction with one of the other two links. The search form link gathers user information for use with the search link. The following figure is an example of how the BOS list link is used. The BOS list link generates a list of user-accessible objects and displays it in the Data Views portion of the Global Services portal Web page. The list items contain a link that passes the object type to the search form link in a URL when the object has one or more attributes with a search-able element value set to true. The search form link uses the business object definition of the object to construct a form for gathering user input. When the search-able element value for an attribute of the object is set to true, the attribute is included in the search form. For example, Global Services displays the Search Audit - Results form to the user as shown in the following figure. PLM00091 J Global Services Customization Guide 5-13

84 Chapter 5 Customizing the user interface User input is passed to the search link, which uses it to create the required query and displays the results to the user. If the user clicks the Apply checkbox, the search form supplies the iscriteria[n] parameter with its value set to true for that field in the URL sent to the search link. The search link uses this parameter as follows: If the URL contains iscriteria[n] parameters with their values set to true (case sensitive), the corresponding FieldName[n] and FieldValue[n] parameter values are used as search criteria regardless of their value. The search criteria NULL is specially treated to search for null values rather than a string consisting of the characters N, U, L, and L. If the URL contains iscriteria[n] parameters with their values set to false (case sensitive) the corresponding FieldName[n] parameters are not used as search criteria. The following figure shows the result of a audit results query Global Services Customization Guide PLM00091 J

85 Customizing the user interface If the object does not have any attributes that have a search-able element set to true, the search-form link automatically forwards to the search link. Clicking the BOS list displays the search result page directly. If the business object definition contains a param element with a max_objects attribute name, the search link uses the element value to limit the number of objects returned by the query. For more information, see the param element description in the Global Services Configuration Guide. The search link can return an object or set of objects by itself if additional input from the user is not required. When the user clicks on the first result ID and selects Associated Message in the previous figure, Global Services generates the following HTTP request: Object=Message&Fields=1&FieldName1=ResultID&FieldValue1= The link contains the search criteria, so no input from the user is required. This can also be accomplished from a menu that is accessed when the user clicks on an employee number. The menu provides a list of links the users chooses from and generates a URL dependent on the selection. You can provide any standard or custom link functionality using a menu. Compute and compute form links These links are typically used in conjunction with each other. The compute form link gathers user information for use with the compute link. Clicking Compute accesses the compute form for the employee objects. When a user chooses the Compute link, Global Services generates the following HTTP request: PLM00091 J Global Services Customization Guide 5-15

86 Chapter 5 Customizing the user interface Object=Employee The compute form link displays a form containing the object attributes as defined in the business object definition. The COUNT, MAX, and MIN functions are available for use on any of the attributes. The AVG and SUM functions are valid for numeric value fields only and Global Services returns an error if they are used in other type fields. Only one function is supported at a time. When a user enters the SUM function in the Bonus field and clicks Continue, Global Services generates the following HTTP request: Employee&attribute=Bonus&operation=SUM The compute link returns the results to the user. Delete and delete form links These links are typically used in conjunction with each other. The delete form link displays the object attributes in read-only fields so the user can confirm that they are deleting the correct object. The delete link performs the actual removal of the object. Clicking Edit accesses a menu with valid link actions for the object in that row. The available actions for the employee object include the delete action. When a user chooses the Delete option, Global Services generates the following HTTP request: 5-16 Global Services Customization Guide PLM00091 J

87 Customizing the user interface Object=EmployeeFields=1&FieldName1=EMPNO& FieldValue1= The delete form link displays a form containing all the object attributes not defined as hidden in the business object definition. The user clicks the Continue button to confirm the delete action and Global Services generates the following HTTP request: 1&FieldName1=EMPNO&FieldValue1= Global Services returns the results of the delete action to the user in a display similar to the compute results. Expand link The expand link uses the business object definition to determine and return a relationship for an object. This link is usually accessed from a link provided when an object is returned as a query result. For example, a query for an employee returns the employee object in a table. This table includes the employee number attribute. Global Services generates the following HTTP request when the user selects the Department Manager option from the employee number menu: Department&Relation=mgr&Fields=1&FieldName1=DEPTNO&FieldValue1=A00 PLM00091 J Global Services Customization Guide 5-17

88 Chapter 5 Customizing the user interface Insert and insert form links These links are typically used in conjunction with each other. The insert form link gathers user information for use with the insert link. The insert form can be accessed by clicking the Insert link available on the bottom left of the page. When a user clicks the Insert link, Global Services generates the following HTTP request: The insert form link displays a form containing the object attributes as defined in the business object definition. The attributes appear in editable text fields as shown in the following figure. Users enter the new employee information in the editable fields and submit the changes to the insert link in an HTTP request when they click the Continue button. The Insert link displays the result of the insert action as shown in the following figure Global Services Customization Guide PLM00091 J

89 Customizing the user interface Update and update form link These links are typically used in conjunction with each other. The update form link gathers user information for use with the update link. Clicking Edit accesses a menu with valid link actions for the object in that row. The available actions for the employee object include the update action. When a user chooses the Update option, Global Services generates the following HTTP request: &Fields=1&FieldName1=EMPNO&FieldValue1= The update form link displays a form containing the object attributes that do not have a hidden element value set to true as defined in the business object definition. The attributes that have their update-able element value set to true appear in editable text fields. PLM00091 J Global Services Customization Guide 5-19

90 Chapter 5 Customizing the user interface Users change the information in the editable fields and submit the changes to the update link in an HTTP request when they click the Continue button. The update link can also be used alone when the user does not need to supply the updated information. Using style sheets In Global Services products, XSL style sheets were used to render the HTML result of the actions. These were combined into your interface, usually through framed HTML. Global Services uses only a few style sheets to provide error and status information, as shown in the following table. You can customize these style sheets, if desired. These XSL files can be found under the i18n/common/xsl directory inside the initial_datastore_full.zip file. Style sheet error.xsl message-result.xsl Description Formats error output. Converts the XML returned from the message server into locale-specific HTML. For a description of the XML format, see the messageresult.dtd file presentation elements Global Services Customization Guide PLM00091 J

91 Customizing the user interface Style sheet result.xsl Description Formats results output for links that have simple results (such as status results). Keep the following in mind if you develop response chains that produce HTML output by transforming XML: You can edit the standard style sheets to provide the desired look and feel or create new style sheets based the existing standard style sheets. To ensure consistency with the XML data generated by response chains, you must provide a DTD for the new style sheet, or use a standard Global Services style sheet. Global Services provides the following style sheets: error.xsl install-status.xsl message-result.xsl result.xsl For maintainability, Siemens PLM Software recommends that you name the XSL file to match the name of the DTD; if a copy of an existing DTD is used, change the name to match the XSL file. The existing DTDs are provided inline from the DTDHolder class. For explanations of the existing DTDs, see Presentation elements. The output and style parameters can be specified in the URL to control the link output. The output parameter has one of the following values: Value html xml status Description Outputs normal XSL style sheet transformation. This is the default used if the output parameter is not specified. Outputs raw XML (without applying any XSL transformations). Outputs status information. Presentation elements If you want to modify the XSL style sheets described in Using style sheets, you must know the structure of the DTD of the XML document that the XSL style sheet operates on. This following describes the use of XML elements specified by each DTD. The elements are grouped according to their DTD and listed alphabetically within the groups. These DTDs are contained in the DTDHolder class which generates this information inline in the output presentation XML files. The following DTDs are described: error.dtd messageresult.dtd result.dtd PLM00091 J Global Services Customization Guide 5-21

92 Chapter 5 Customizing the user interface error.dtd <!-- The Global Services error DTD version > <!ELEMENT error (aetitle text tracking trace type class)*> <!ELEMENT aetitle (#PCDATA)> <!ELEMENT text (#PCDATA)> <!ELEMENT tracking (#PCDATA)> <!ELEMENT trace (#PCDATA)> <!ELEMENT type (#PCDATA)> <!ELEMENT class (#PCDATA)> The following elements are defined in the error.dtd file: aetitle (optional) class (optional) error (required) text (optional) tracking (optional) trace (optional) type (optional) 5-22 Global Services Customization Guide PLM00091 J

93 Customizing the user interface aetitle PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the title string for a Global Services exception user interface message. This element is optional. <aetitle>globalservices-exception-user-interface-message-title</aetitle> None. <aetitle>operation Error</aetitle> PLM00091 J Global Services Customization Guide 5-23

94 Chapter 5 Customizing the user interface class PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the class name of the Java exception for this error. This element is optional. <class>fully-qualified-classname-of-java-exception</class> None. <class>java.lang.noclassdeffounderror</class> 5-24 Global Services Customization Guide PLM00091 J

95 Customizing the user interface error PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the text of an error message. This is the top-level element for an error message. This element is required. <error>error-information-elements</error> None. <error> A class could not be found. Check the existence of the class or the classpath. </error> PLM00091 J Global Services Customization Guide 5-25

96 Chapter 5 Customizing the user interface text PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies a string to be used for this error message or a user interface error message. This element is optional. <text>message-text</text> None. <text> Your request could not be completed within the Global Services system. Please contact your Global Services Administrator. </text> 5-26 Global Services Customization Guide PLM00091 J

97 Customizing the user interface trace PURPOSE SYNTAX ATTRIBUTES EXAMPLE Contains the complete stack trace output of the Java exception thrown when this error occurred. This element is optional. Siemens PLM Software recommends that you use the log4j logging object to save the exception stack trace to a log file. This information is not normally of use to the user and, therefore, is not appropriate for display at the user interface. For information about logging Global Services exceptions, see Exception coding and logging conventions. <trace>. stack-trace-output-of-java-exception. </trace> None. <trace> java.lang.noclassdeffounderror: javax/ejb/ejbobject at java.lang.classloader.defineclass0(native Method) at java.lang.classloader.defineclass(unknown Source) at java.security.secureclassloader.defineclass(unknown Source) at java.net.urlclassloader.defineclass(unknown Source) at java.net.urlclassloader.access$100(unknown Source) at java.net.urlclassloader$1.run(unknown Source) at java.security.accesscontroller.doprivileged(native Method) at java.net.urlclassloader.findclass(unknown Source) at java.lang.classloader.loadclass(unknown Source) at java.lang.classloader.loadclass(unknown Source) </trace> PLM00091 J Global Services Customization Guide 5-27

98 Chapter 5 Customizing the user interface tracking PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the string to be used to help administrators correlate a user s error message with detailed Global Services exception message information in the log file. This element is optional. <tracking></tracking> None. <tracking> Error ID: [ ] (Please save for your administrator.) </tracking> 5-28 Global Services Customization Guide PLM00091 J

99 Customizing the user interface type PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the category for the error. This element is optional. <type>error-category</type> None. <type>error category</type> messageresult.dtd <!-- The Global Services message result DTD version > <!ELEMENT MessageResult (status, ReactorResult*)> <!ELEMENT status EMPTY> <!ATTLIST status value (passed failed unprocessed) #REQUIRED> <!ELEMENT ReactorResult (details?)> <!ATTLIST ReactorResult name CDATA #REQUIRED status (passed failed unprocessed) #REQUIRED> <!ELEMENT details (#PCDATA)> The MessageResult DTD elements define the XML format for the messages returned by the message server as a response from a reactor. The following elements are defined in the messageresult.dtd file: details (optional) MessageResult (required) ReactorResult (optional) status (optional) PLM00091 J Global Services Customization Guide 5-29

100 Chapter 5 Customizing the user interface details PURPOSE SYNTAX ATTRIBUTES EXAMPLE Returns the information stored in the details property of a Global Services exception when a reactor throws a Global Services exception. This element is optional. <details>result-string</details> None. <details> Process failed to complete, data source unavailable. </details> NOTES The result string cannot contain a close bracket character (]) followed immediately by a close bracket and less than character (]>) Global Services Customization Guide PLM00091 J

101 Customizing the user interface MessageResult PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the reactor response data returned by the message server. This is the top-level element for the message server response message. This element is required. <MessageResult> <status /> <ReactorResult>. </ReactorResult>. </MessageResult> None. <MessageResult> <status value="failed" /> <ReactorResult name="r1" status="passed"> </ReactorResult> <ReactorResult name="r2" status="failed"> <details> Details about Global Services exception thrown by the reactor </details> </ReactorResult> </MessageResult> PLM00091 J Global Services Customization Guide 5-31

102 Chapter 5 Customizing the user interface ReactorResult PURPOSE SYNTAX ATTRIBUTES EXAMPLE Identifies a reactor and the status of the received message. This element is optional. <ReactorResult name="name-of-reactor" status=passed failed" /> name Specifies the name of the reactor. This attribute is required. status Specifies whether the reactor handled the message correctly or if an error occurred. This attribute is required. Valid status values are passed or failed. <ReactorResult name="r1" status="passed" /> 5-32 Global Services Customization Guide PLM00091 J

103 Customizing the user interface status PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the status of a message. This element is required. <status value="passed failed unprocessed" /> value Specifies the overall status of a message. This attribute is required. The valid values for status are passed, which indicates that all reactors returned a passed status, failed, which indicates that one or more reactors returned failed status, or unprocessed, which indicates the message was not sent from the queue. <status value="unprocessed" /> result.dtd <!-- The Global Services result DTD version > <!ELEMENT result (operation function data)*> <!ELEMENT operation EMPTY> <!ATTLIST operation name CDATA #REQUIRED> <!ELEMENT data (#PCDATA)> <!ELEMENT function EMPTY> <!ATTLIST function name CDATA #REQUIRED> The following elements are defined in the result.dtd file: data (optional) function (optional) operation (optional) result (required) PLM00091 J Global Services Customization Guide 5-33

104 Chapter 5 Customizing the user interface data PURPOSE SYNTAX EXAMPLE Specifies the output of special operations. This element is optional. The results do not consist of a table of data but are either single-line messages or downloaded file URLs. <data>result</data> <data>record deleted from Employee.</data> 5-34 Global Services Customization Guide PLM00091 J

105 Customizing the user interface function PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the function for a compute operation or the name of a downloaded file resulting from the download operation. This element is optional. <function name="compute-function" /> name Specifies the name of the function executed through the Global Services client API or the displayed name of a downloaded file. This attribute is required. <function name="count(*)" /> PLM00091 J Global Services Customization Guide 5-35

106 Chapter 5 Customizing the user interface operation PURPOSE SYNTAX ATTRIBUTES EXAMPLE Specifies the Global Services operation completed or to be performed. This element is optional. <operation name="client-operation" /> name Specifies the name of the operation executed through the Global Services client API. This attribute is required. <operation name="delete" /> 5-36 Global Services Customization Guide PLM00091 J

107 Customizing the user interface result PURPOSE SYNTAX EXAMPLE Specifies simple output data or information from a request. This element is required. This is the top-level element for the XML request result obtained through the execution of an operation. This structure is used where the result is a single piece of information, such as a link or text string. <result> result-information-elements </result> <result> <function name="compute" /> <operation name="update" /> <data>35</data> </result> PLM00091 J Global Services Customization Guide 5-37

108

109 Chapter 6 Supporting local languages Supporting local languages Using ID maps Using localized transformation files Using text bundles PLM00091 J Global Services Customization Guide

110

111 Chapter 6 Supporting local languages Supporting local languages Any customizations that you make to Global Services must conform to this process. This process also allows you to customize your installation to support languages that are not supplied with Global Services. Global Services provides support for displaying information to users in their native language. However, Global Services does not translate information from data sources. Global Services displays information from a data source in the language that it is stored in on the data source. Text bundles provide Global Services messages in the user s native language and XSL style sheets provide native language output for text portions of the Global Services Web interface. The sample user interface components and the connectors provide the majority of the localization support in Global Services. Data supplied by the user or by a data source is passed through Global Services to its destination unchanged from the original language. This is accomplished by using Unicode for the majority of the communications between Global Services components. Using ID maps Global Services provides the IDMap class to help you localize your business object definitions. Each supported locale requires a separate IDMap.xml that contains the TextID attributes and their corresponding translated text strings. Place these files in the Global Services /i18n subdirectories in the Global Services datastore for each language that you need to support. For more information about IDMap.xml files, see the Global Services Configuration Guide. The IDMap class also contains the getmappedtext method that you use to retrieve the text string for a TextID from memory. The following BOSClient class methods are associated with localization: getattributetextid getmappedobjectname getobjecttextid For more information, see Using the convenience classes. The business object definition file provides the label element with an ID attribute that is used in conjunction with the TextID element. The following listing shows label elements used in a business object definition: <!-- Department business object definition --> <?xml version="1.0" encoding="utf-8" standalone="yes"?> <!--bcprt This software and related documentation are proprietary to UGS Corp. COPYRIGHT 2005 UGS CORP. ALL RIGHTS RESERVED PLM00091 J Global Services Customization Guide 6-1

112 Chapter 6 Supporting local languages ecprt --> <business-object-definition name="employee" xmlns:xsi=" xmlns:conn=" xsi:nonamespaceschemalocation="business-object-definition.xsd" xmlns=" <label ID="Employee.name"/> <data-source name="local DB2"> <data-segment name="a"> <conn:data-source-spec JNDI-name="TcGSJDBCBox" config-name="db2databaseconfig"/> <class-name>employee</class-name> <insert-able>true</insert-able> <delete-able>true</delete-able> <compute-able>true</compute-able> <attribute name="empno"> <label default="employee No." ID="Employee.attr.EMPNO"/> <name-on-source>empno</name-on-source> <primary-key>true</primary-key><search-able>true</search-able> <link name="all Employees" href="search?object=employee&fields=0"> <label ID="SAMPLE.link.AllEmp"/> </link> <link name="all Departments" href="search?object=department&fields=0"> <label ID="SAMPLE.link.AllDept"/> </link> <link name="department Manager" href="expand?object=department&relation=m gr&fields=1&fieldname1=deptno&fieldvalue1=this.workdept"> <label ID="Employee.link.DeptMgr"/> </link> </attribute> <attribute name="firstname"> <label default="first Name" ID="Employee.attr.FirstName"/> <name-on-source>firstnme</name-on-source> <required-for-insert>true</required-for-insert> <search-able>true</search-able> <update-able>true</update-able> </attribute> <attribute name="lastname"> <label default="last Name" ID="Employee.attr.LastName"/> <name-on-source>lastname</name-on-source> <search-able>true</search-able> <update-able>true</update-able> </attribute> <attribute name="mi"> <label default="initial" ID="Employee.attr.MI"/> <name-on-source>midinit</name-on-source> <update-able>true</update-able> <valid-value>a</valid-value><valid-value>b</valid-value><valid-value>c</valid-value> <valid-value>d</valid-value><valid-value>e</valid-value><valid-value>f</valid-value> <valid-value>g</valid-value><valid-value>h</valid-value><valid-value>i</valid-value> <valid-value>j</valid-value><valid-value>k</valid-value><valid-value>l</valid-value> <valid-value>m</valid-value><valid-value>n</valid-value><valid-value>o</valid-value> <valid-value>p</valid-value><valid-value>q</valid-value><valid-value>r</valid-value> <valid-value>s</valid-value><valid-value>t</valid-value><valid-value>u</valid-value> <valid-value>v</valid-value><valid-value>w</valid-value><valid-value>x</valid-value> <valid-value>y</valid-value><valid-value>z</valid-value> </attribute> <attribute name="workdept"> <label default="department" ID="Employee.attr.WorkDept"/> <name-on-source>workdept</name-on-source> <update-able>true</update-able> <dynamic-valid-value object="department" attribute="deptno"/> <link href="search?object=department&fields=1&fieldname1=deptno&f ieldvalue1=this.workdept&isvalueliteral1=true"></link> </attribute> <attribute name="phoneno"> <label default="phone No." ID="Employee.attr.PhoneNo"/> <name-on-source>phoneno</name-on-source> <update-able>true</update-able> </attribute> <attribute name="hiredate"> <label default="hire Date" ID="Employee.attr.HireDate"/> <name-on-source>hiredate</name-on-source> <update-able>true</update-able> </attribute> <attribute name="title"> <label default="title" ID="Employee.attr.Title"/> <name-on-source>job</name-on-source> <search-able>true</search-able> <value-map-name>employeetitlemap</value-map-name> <update-able>true</update-able> </attribute> <attribute name="edlevel"> <label default="educ. Level" ID="Employee.attr.EdLevel"/> <type>int</type> <search-able>true</search-able> <hidden>true</hidden> </attribute> <attribute name="sex"> <label default="sex" ID="Employee.attr.Sex"/> <hidden>true</hidden> 6-2 Global Services Customization Guide PLM00091 J

113 Supporting local languages </attribute> <attribute name="birthdate"> <label default="birthday" ID="Employee.attr.BirthDate"/> <hidden>true</hidden> </attribute> <attribute name="salary"> <label default="salary" ID="Employee.attr.Salary"/> <type>double</type> <update-able>true</update-able> </attribute> <attribute name="bonus"> <label default="bonus" ID="Employee.attr.Bonus"/> <type>double</type> <update-able>true</update-able> </attribute> <attribute name="comm"> <label default="commission" ID="Employee.attr.Comm"/> <type>double</type> <update-able>true</update-able> </attribute> </data-segment> </data-source> </business-object-definition> The TextID element is provided in the locale-specific IDMap.xml file. This element also contains the translated text string for the specific locale in its text attribute. You can use this element in to provide localization of static text generated by a custom. For each locale that you support, you must provide an IDMap.xml file in the /i18n/language location of the Global Services datastore. The language_country location name should conform to the two lowercase-letter language (for example, fr). The following listing shows an excerpt from the IDMap.xml file for the en locale: <!-- ID map XML file --> <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE IDMap SYSTEM "../common/idmap.dtd">. <!-- TRANSLATION NOTE: Only translate the information defined by the text= tag. The name tag must not be translated.--> <IDMap> <!-- DEFINTIONS USED BY CORE GLOBAL SERVICES --> <!-- Definitions used when creating a business object list --> <TextID name="boslist.name" text="object"/> <TextID name="boslist.attr.objectname" text="business Object Name"/> <!-- DEFINTIONS OF THE SAMPLE DB2 DATABASE OBJECTS --> <!-- Common Definitions used by one or more objects --> <!-- The external display names of the common links --> <TextID name="sample.link.alldept" text="all Departments"/> <TextID name="sample.link.allemp" text="all Employees"/> <TextID name="sample.link.empdept" text="employees in Department"/> <!-- Employee Business Object Definitions --> <!-- The external display name of the object --> <TextID name="employee.name" text="employee"/> <!-- The external display names of the object attributes --> <TextID name="employee.attr.empno" text="employee No."/> <TextID name="employee.attr.firstname" text="first Name"/> <TextID name="employee.attr.lastname" text="last Name"/> <TextID name="employee.attr.mi" text="initial"/> <TextID name="employee.attr.workdept" text="department"/> <TextID name="employee.attr.phoneno" text="phone No."/> <TextID name="employee.attr.hiredate" text="hire Date"/> <TextID name="employee.attr.title" text="title"/>. <!-- The external display names of the object links --> <TextID name="employee.link.deptinfo" text="department Information"/> <TextID name="employee.link.deptmgr" text="department Manager"/> <!-- Department Business Object Definitions --> <!-- The external display name of the object --> <TextID name="department.name" text="department"/> <!-- The external display names of the object attributes --> <TextID name="department.attr.deptno" text="department No."/> <TextID name="department.attr.deptname" text="department Name"/> <TextID name="department.attr.mgrno" text="manager No."/> <TextID name="department.attr.admrdept" text="admin. Department"/> <!-- EmpDept Business Object Definitions --> <!-- Since the EmpDept Business Object combines information from both the Employee and Department business objects, most of the labels used by EmpDept are defined previously. --> <!-- The external display name of the object --> <TextID name="empdept.name" text="employee Summary"/> <!-- The external display names of the unique attributes --> PLM00091 J Global Services Customization Guide 6-3

114 Chapter 6 Supporting local languages <TextID name="empdept.attr.mgrfirstname" text="manager First Name"/> <TextID name="empdept.attr.mgrlastname" text="manager Last Name"/> <!-- DEFINITIONS FOR EXAMPLE BUSINESS OBJECT AND --> <!-- EXAMPLE Acronym Business Object Definitions --> <!-- The external display name of the object --> <TextID name="acronym.name" text="acronym"/> <!-- The external display names of the object attributes --> <TextID name="acronym.attr.acronym" text="acronym"/> <TextID name="acronym.attr.explanation" text="explanation"/> <!-- EXAMPLE DEFINITIONS --> <!-- The example dynamically generates information tables. The following definitions are used by the example to provide local language translations for the table headings and type information. --> <!-- Definition of example table headings for attribute information. --> <TextID name="example.attrinfo.attrname" text="attribute Name"/> <TextID name="example.attrinfo.dataname" text="data Name"/> <TextID name="example.attrinfo.label" text="label"/> <TextID name="example.attrinfo.default" text="default"/> <TextID name="example.attrinfo.type" text="type"/> <!-- Background Color --> <TextID name="example.attrinfo.bgcolor" text="background Color"/> <TextID name="example.attrinfo.primary" text="primary"/> <TextID name="example.attrinfo.search" text="search"/> <TextID name="example.attrinfo.update" text="update"/> <!-- Definition of example table headings for relationship information. --> <TextID name="example.relinfo.relation" text="relation"/> <TextID name="example.relinfo.object" text="object"/> <TextID name="example.relinfo.result" text="result"/> <TextID name="example.relinfo.rootclass" text="root Class"/> <TextID name="example.relinfo.segment" text="segment"/> <TextID name="example.relinfo.formal" text="formal"/> <TextID name="example.relinfo.informal" text="informal"/> <!-- Definitions of the example type identifiers --> <TextID name="example.type.unknown" text="?"/> <TextID name="example.type.string" text="string"/> <TextID name="example.type.int" text="integer"/> <TextID name="example.type.smallint" text="small integer"/> <TextID name="example.type.bigint" text="big integer"/> <TextID name="example.type.double" text="double"/> <TextID name="example.type.float" text="float"/> <TextID name="example.type.date" text="date"/> <TextID name="example.type.time" text="time"/> <TextID name="example.type.timestamp" text="timestamp"/> <!-- Definitions of the Iman business object definitions --> <TextID name="iman.attr.object_string" text="part Name"/> <TextID name="iman.attr.items_tag.item_id" text="part No"/> <TextID name="iman.attr.release_status_list" text="life Cycle Status"/> <TextID name="iman.attr.object_desc" text="part Description"/> <TextID name="iman.attr.item_revision_id" text="revision"/> <!-- Definitions of the Enterprise business object definitions --> <TextID name="meta.attr.displayedname" text="part Name"/> <TextID name="meta.attr.partnumber" text="part No"/> <TextID name="meta.attr.lifecyclestate" text="life Cycle Status"/> <TextID name="meta.attr.nomenclature" text="part Description"/> <TextID name="meta.attr.revision" text="revision"/> </IDMap> Note To compile, deploy, and use a customization with localization support, you must have the following files included in your CLASSPATH environment variable: globalservicescore.jar log4j.jar The sample code uses the TextID element to obtain localized text to display as headings for a business object s relationship information. The following code example contains a portion of the Example.java file that shows how this can be done: //Example.java fragment file 1:private String getrelations( Client cl, String cb) throws GlobalServicesException 2:{ 3: // Get the business object name from the client. 4: String bo = cl.getobjectname(); 5: 6: // Generate the TextID associated with the column 7: // headers in the table. The TextID contains the ID 8: // index into the IDMap and a default value in case 9: // a mapped value cannot be found for a given local. 10: TextID rln = new TextID("example.relinfo.relation", 6-4 Global Services Customization Guide PLM00091 J

115 Supporting local languages 11: "Relation"); 12: TextID obj = new TextID("example.relinfo.object", 13: "Object"); 14: TextID result = new TextID("example.relinfo.result", 15: "Result"); 16: TextID root_class = new TextID("example.relinfo.rootclass", 17: "Root Class"); 18: TextID sgmnt = new TextID("example.relinfo.segment", 19: "Segment"); 20: TextID formal = new TextID("example.relinfo.formal", 21: "Formal"); 22: TextID in_formal = new TextID("example.relinfo.informal", 23: "Informal"); 24: 25: // Initialize the string buffer with a reasonable size. 26: StringBuffer sb = new StringBuffer(2000); 27: 28: String locale_string = String.valueOf(cl.getLocale()); 29: 30: // Generate Global Services standard XML header information. 31: sb.append(xmlconstants.xml_header + "\n"); 32: 33: // Generate the DTD. 34: sb.append( getdtd()); 35: 36: 37: // Get the list of relation names for this object. 38: Vector relations = cl.getrelationnames( bo); 39: 40: sb.append("<table>\n"); 41: 42: // Add the business object. 43: sb.append("<object name=\"" + bo + "\" label=\"" 44: + cl.getmappedobjectname(bo) + 45: "\" /> \n"); 46: 47: // Put the number of relations in the table XML 48: sb.append("<resultsize value=\"" + relations.size() + "\" />\n"); 49: sb.append("<operation name=\"query\" />\n"); 50: sb.append("<header>\n"); 51: 52: // Generate the XML elements for the header information. 53: // The header includes the name of the attribute 54: // and the display label. The label is determined by using 55: // an IDMap lookup for the user s locale. 56: sb.append("<attribute name=\"relation\" label=\"" 57: + IDMap.getMappedText( rln, locale_string) + 58: "\" /> \n"); 59: sb.append("<attribute name=\"object\" label=\"" 60: + IDMap.getMappedText(obj, locale_string) + 61: "\" />\n"); 62: sb.append("<attribute name=\"result\" label=\"" 63: + IDMap.getMappedText(result, locale_string) + 64: "\" />\n"); 65: sb.append("<attribute name=\"rootclass\" label=\"" 66: + IDMap.getMappedText(root_class, locale_string) + 67: "\" />\n"); 68: sb.append("<attribute name=\"segment\" label=\"" 69: + IDMap.getMappedText(sgmnt, locale_string) + 70: "\" />\n"); 71: sb.append("<attribute name=\"formal\" label=\"" 72: + IDMap.getMappedText(formal, locale_string) + 73: "\" /> \n"); 74: sb.append("<attribute name=\"informal\" label=\"" 75: + IDMap.getMappedText(in_formal, locale_string) + 76: "\" />\n"); 77: sb.append("</header>\n"); 78: sb.append("<code_base name=\"" + cb +"\" />\n"); 79: sb.append("<data>\n"); 80: 81: // Loop throught the relation name list and get 82: // the information about each relation. 83: for (int i=0; i < relations.size(); i++) 84: { 85: Relation relation = cl.getrelation( bo,(string) relations.elementat(i)); 86: sb.append(getrelationinfo( relation)); 87: } 88: 89: // Close the XML. 90: sb.append("</data>\n</table>"); 91: 92: return sb.tostring(); 93:} Lines of the listing creates a TextID object for each column heading using the TextID name attribute value and a default text value. The default text value is a string that is used if a locale-specific text attribute cannot be found in the ID map. The TextID object holds the ID map index of the name attribute. Line 28 PLM00091 J Global Services Customization Guide 6-5

116 Chapter 6 Supporting local languages gets the user s locale as a string that is used along with the TextID objects (lines 56 76) as the parameters to the getmappedtext method. This method returns the locale-specific text string for the attribute from the ID map. Additionally, the BOSClient class s getmappedobjectname method (lines 43 44) is used to obtain the object name for the user s locale from the ID map. Using localized transformation files Global Services includes XSL style sheets that provide transformation of the XML information to a format (usually HTML) for display to the user. The style sheets include a set of common files that generate information that is not language specific. These common style sheets are located in the /i18n/common location of the Global Services datastore. Additionally, each supported language has a directory under the Global Services i18n location that contains style sheets that include string variables to use for local language text strings. These language-specific files include the common file by reference and encapsulate the language-specific information. This allows you to customize the common style sheets to control portions of the user interface for all locales. Other parts of the user interface are controlled through JSP files that also allow you to customize the UI. Any new attributes strings or other information that the transformation supplies to the user interface are added to the local language style sheet as string variables. For a description of the standard Global Services style sheets, see Using style sheets. The following listing shows the an example of the contents of the result.xsl file for the de_de locale: <!-- Language-specific XSL file --> <xsl:transform xmlns:xsl=" version="1.0"> <xsl:output method="html" indent="yes"/> <xsl:preserve-space elements="*"/> <!-- i18n Strings --> <!-- The (generic) title for results --> <xsl:variable name="resulttitle">ergebnisse</xsl:variable> <!-- The (generic) result label --> <xsl:variable name="resultlabel">ergebnis für </xsl:variable> <!-- The label for Compute results. --> <xsl:variable name="computelabel">ergebnisse für Berechnungsanforderung </xsl:variable> <!-- The label for Delete results. --> <xsl:variable name="deletelabel">ergebnisse für Löschanforderung </xsl:variable> <!-- The label for a File upload result. --> <xsl:variable name="uploadlabel">hochladeergebnis </xsl:variable> <!-- The label for a File download result. --> <xsl:variable name="downloadlabel">datei heruntergeladen </xsl:variable> <!-- The label for a TCEng File upload result. --> <xsl:variable name="tcenguploadlabel">datei-upload-ergebnis </xsl:variable> <!-- The label for a TCEng File download result. --> <xsl:variable name="tcengdownloadlabel">datei-download-ergebnis </xsl:variable> <!-- The label for a TCEng check-out result. --> <xsl:variable name="checkoutlabel">auscheck-ergebnisse </xsl:variable> <!-- The label for a TCEng check-in result. --> <xsl:variable name="checkinlabel">eincheck-ergebnisse </xsl:variable> <!-- The label for the Publish message (to the message server). --> <xsl:variable name="publishlabel">nachricht an Nachrichten-Server veröffentlicht </xsl:variable> <!-- The label for the command message (to the message server). --> <xsl:variable name="msg_adminlabel">befehl an Nachrichten-Server versendet </xsl:variable> <!-- The product name --> <xsl:variable name="productname">teamcenter Global Services</xsl:variable> <!-- END i18n Strings --> <!- Īnclude the common rules for generating non-language specific HTML. --> <xsl:include href="../../common/xsl/result.xsl"/> </xsl:transform> 6-6 Global Services Customization Guide PLM00091 J

117 Supporting local languages Using text bundles The TextBundle class is an extension of the standard Java ListResourceBundle class that contains a text ID associated with the message text. TextBundle classes can be defined for a specific package and a separate class is created for each supported language. You can use the TextBundle class for your own localization. To support a new locale, create a new TextBundle class using this default locale TextBundle class as the starting point. The new TextBundle class must reside in the same package as the starting default locale text bundle. For example, to support French, create the file TextBundle_fr.java file from the TextBundle.java file. Edit the new TextBundle_fr.java file to change the class name to TextBundle_fr and translate the individual text in each text bundle unit. This newly created class is used instead of the default text bundle when the locale is set to fr, fr_fr, fr_ca, fr_ch, or fr_be. The Java compiler (javac) can process source files in ASCII or Unicode encodings only. If the source file for the text bundle is converted to an encoding such as EUC, you must use the Javasoft native2ascii tool to convert it to ASCII before it can be compiled. All static message text can be stored in easily translated Java files. The message contents are retrieved at runtime using the methods in the class. To retrieve text, you must provide at least the text identifier of the string to be retrieved from the resource bundle class plus the fully qualified name of the text bundle for the default locale. This fully qualified name is typically the name of the Java package. The text identifiers are stored in the package-name.textbundleids class and the text itself is stored in the package-name.textbundle class. The following is an example of a TextBundleIDs class: package example.handler; import com.teamcenter.globalservices.msg.textbundleid; /** * This example TextBundleIDs class holds unique identification strings * for the user interface messages corresponding to the * <code>exampleglobalservicesexception</code> class. * The <code>exampleglobalservicesexception</code> subclass is * identified by an ID from this interface. * <p> * The ID tags also are used for looking up internationalized * text messages. These IDs map to text strings which are general * messages, suitable for display in the end-user interface, * describing the type of exception that occurred. * <p> * For an example of a resource bundle implementation, see the * <code>example.handler.textbundle</code> class. * <p> * TextBundle */ public class TextBundleIDs extends TextBundleID { private static int nextidentifier_ = 1; private TextBundleIDs() { super("0" + nextidentifier_++, TextBundle.class); } public static final TextBundleIDs BOD_UPDATED_TAG = new TextBundleIDs(); public static final TextBundleIDs BOD_UPDATE_FUNCTION = new TextBundleIDs(); public static final TextBundleIDs SUBMIT_BUTTON_LABEL = new TextBundleIDs(); public static final TextBundleIDs BOD_EDIT_FORM_TITLE = new TextBundleIDs(); This example defines text IDs for four messages. The first message is a message stating that a particular business object definition is being updated in the datastore. The following example shows how the TextBundle class defines this message and others: package example.handler; import java.util.listresourcebundle; PLM00091 J Global Services Customization Guide 6-7

118 Chapter 6 Supporting local languages /** * Holds text messages for localization. * <p> * This class holds the messages used in this Java package. Each message has a * tag name from the <code>example.handler.textbundleids</code> class. */ public class TextBundle extends ListResourceBundle { // Returns the contents of the bundle. public Object[][] getcontents() { return ContentHolder.CONTENTS; } private static class ContentHolder { // Holds the messages to be localized. // LOCALIZE THIS private static final String[][] CONTENTS = { { TextBundleIDs.BOD_UPDATED_TAG.toString(), }, { }, { }, { "{0} BOD updated in datastore" // Name of the business object definition file being updated in the // datastore. TextBundleIDs.BOD_UPDATE_FUNCTION.toString(), "BOD Update Function" TextBundleIDs.SUBMIT_BUTTON_LABEL.toString(), "Submit to Datastore" TextBundleIDs.BOD_EDIT_FORM_TITLE.toString(), "Submit to Datastore" }, }; // END OF MATERIAL TO LOCALIZE } } // TextBundle.java You can use the TextMessage class constructor methods to create your message object or the L10nUtil class to statically get a message for a specific text ID. To create a message object associated with a particular locale, use the following method: TextMessage tm = new TextMessage TextBundleIDs.TEXT_ID, getlocale()); To create a text message associated with the component default locale, use the following method: TextMessage tm = new TextMessage TextBundleIDs.TEXT_ID; Then to retrieve the message string, use the following method: String msg = tm.getmessage(); You can also use text insert references to insert runtime data into a defined message. The message is defined with insert references using the {0} [, {1},...] character sequence. At runtime, the inserts are placed in an object array with values for each of the position-dependent arguments. The objects can be any type that has a tostring method. For example, a method might return a result message indicating that an incorrect parameter was specified. The following example shows how to generate this message: if (invalid parameter value detected) { Object[] arguments = { parameter-name, parameter-value }; TextMessage tm = new TextMessage TextBundleIDs.TEXT_ID, arguments); String msg = tm.getmessage(); } 6-8 Global Services Customization Guide PLM00091 J

119 Supporting local languages Using the example TextBundleIDs and TextBundle class, the following line of code shows how to get a message using the L10nUtil class to display a message in the default locale: Import com.teamcenter.globalservices.msg.l10nutil; Import example.handler.textbundleids;. // Get a message L10nUtil.getMessage (TextBundleIDs.BOD_UPDATED_TAG, // The message id to use new Object[] { bod name }, // substitution text null); // default locale, can also specify a locale For more information, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. PLM00091 J Global Services Customization Guide 6-9

120

121 Chapter 7 Exception and message handling Exception and message handling Exceptions Create a custom exception class Message localization and logging Exception coding and logging conventions Creating and logging a Global Services exception Logging non-global Services exceptions Catching Global Services exceptions at the user interface Configuring debug message logging PLM00091 J Global Services Customization Guide

122

123 Chapter 7 Exception and message handling Exception and message handling These instructions and guidelines describe how to use Global Services exception classes and subclasses and create your own Global Services exception subclasses. This is the process that Siemens PLM Software recommends for providing localized system messages to users. How to handle message logging for both Global Services and non-global Services exceptions is also provided. Exception message localization is described and debug message logging information is provided. Exceptions The Global Services presentation tier displays messages from two sources: presentation tier-generated messages and exception messages caught from underlying server components, such as EJBs and utility classes. Presentation tier-generated messages are typically general status messages or user error messages. Global Services displays these messages to the user in the user chosen locale. Messages from the server components or utility classes are typically detailed messages reporting system errors, data source errors, or applications errors, such as problems with business objects. The finer granularity of these messages is not appropriate for most end users. The Global Services exception class handles error messages by providing a mechanism to supply appropriate information to the user in the user s locale and to log the detailed error information in the server s locale for use by the Global Services administrator. The Global Services exception class implements the following: A text storage implementation type for supplying a localized text message string. This is provided through resource bundles and the TextBundle class. A unique ID that identifies the message and a message bundle or storage identifier that specifies the set of text messages where the generated message is stored. An insert argument list that allows you to dynamically insert business object names, attribute names, and other pertinent information into a message. A static text string that is used when it is not necessary or possible to provide a localized string. The message and bundle or storage ID is not used when a static string is provided. An exception classification code that is used to provide a general user message through the presentation layer components. PLM00091 J Global Services Customization Guide 7-1

124 Chapter 7 Exception and message handling An exception history obtained using the exception stack trace that can be stored as a text string in a log file. Global Services exception objects that store additional information. These objects can be used to transfer data to other program components, allowing them to recover from an error situation. A unique 9-digit error ID that is used as a tracing code to assist administrators. This code is displayed to the user and stored with the detailed exception data in the log file. The GlobalServicesException class is the parent class of all Global Services exception subclasses. To create a Global Services exception when an error is detected, you create a subclass exception that best fits the error. Your method that creates the exception should throw the parent class exception. In most cases, your methods may catch the parent class exception, instead of a particular subclass exception. The parent class displays the following general error message to the user: Global Services has encountered a problem and cannot continue. Please contact your Global Services administrator. Global Services provides the following standard exception subclasses: GlobalServicesApplicationException Global Services throws this exception when it encounters an error that stops the system for all users. This is an unrecoverable exception that must be fixed by the Global Services administrator. After the error is fixed, the administrator must restart Global Services to recover from this exception. Some errors that cause this exception are: o A connection manager error occurs. o o Global Services cannot find or create the BOS. Global Services cannot find the runtime data. This exceptions displays the following message to the user: An unrecoverable problem was encountered with the Global Services system. Please contact your Global Services administrator. GlobalServicesCommunicationException Global Services throws this error when it fails to communicate with one of its own components, such as the business object server (BOS) EJB, a connector EJB, or a reactor. Some errors that cause this exception are: o A connection manager error occurs. o o o o Global Services cannot find an EJB or EJB home. A reactor error occurs. A component connection is closed when Global Services expects it to be open. Global Services encounters an error when attempting to remove a connection or a remote component. 7-2 Global Services Customization Guide PLM00091 J

125 Exception and message handling This exceptions displays the following message to the user: Global Services could not communicate with one or more of its components. Please try again, or contact your Global Services administrator. GlobalServicesDataSourceException Global Services throws this exception when it has a problem accessing or getting data to and from a legacy data source system. Some errors that cause this exception are: o Global Services encounters a error with a request string sent to a data source. For example a malformed SQL statement. o The data source throws an exception. This exceptions displays the following message to the user: Global Services encountered a problem using the data source. Please check the data you entered and try again, or contact your Global Services administrator. GlobalServicesDataSrcCommunicationException Global Services throws this exception when it fails to communicate with a legacy data source system. Some errors that cause this exception are: o A data source connection cannot be made due to a network problem. o o Global Services encounters an invalid data source name. Global Services encounters any other problem that prevents a connection. This exceptions displays the following message to the user: Global Services could not communicate with the requested data source system. Please try again, or contact your Global Services administrator. GlobalServicesInvalidDataFormatException Global Services throws this exception when it is unable to find, open, or read the proper elements in one of its data files. Global Services uses the data files to validate security parameters, set up configurations, and to define the business logic to access information from a data source. In standard Global Services, XML files contain the data, but it could reside in other places. For example, an LDAP server can provide security data. You can have Global Services throw this exception for invalid data format from any type of storage system. Some errors that cause this exception are: o The business object definition (XML file) does not conform to the Global Services schema (business-object-definition.xsd). o o o o o Global Services encounters an error while parsing an XML data file. Global Services does not find an expected security, configuration, or business object XML file. Global Services does not find expected elements in an XML data file. Global Services encounters a business object logic or rule error. The business-object-definition.xsd file is missing. PLM00091 J Global Services Customization Guide 7-3

126 Chapter 7 Exception and message handling o An invalid value exists within an XML element. This exceptions displays the following message to the user: Global Services could not access the data necessary to continue. Please try again, or contact your Global Services administrator. GlobalServicesInvalidInputException Global Services throws this exception when a user form or some other user interface (UI) device supplies invalid input. The current Global Services presentation tier does not use this exception, but may use it in the future. You may use this exception class in your customizations. You can provide the detailed error message alone to the user interface or along with the user interface message. Because this is a user error, the error information is not logged. This exceptions displays the following message to the user: Global Services could not process your data. Please check your input and try again, or contact your Global Services administrator. GlobalServicesOperationException Global Services throws this exception when it can not perform its expected function. This exception covers miscellaneous errors that Global Services encounters when performing a single operation for a single user. Some errors that cause this exception are: o Global Services encounters a missing or invalid method parameter. o o o o o o Global Services tries to execute an illegal function. A query returns an invalid number of objects that prevents Global Services from continuing the operation. A Global Services operation (such as compute, delete, download, insert, query, update, or upload ) fails. An error occurs when Global Services attempts to build the XML output. An error occurs when Global Services attempts to convert the XML output to HTML. Global Services encounters an error with an internal data object (DataObject error). This exceptions displays the following message to the user: Your request could not be completed within the Global Services system. Please contact your Global Services administrator. GlobalServicesSecurityException Global Services throws this exception when there are problems validating a user. Some errors that cause this exception are: o A sign-on error occurs or Global Services is unable to create a login o o An LDAP or XML file look-up error occurs. A credentials error occurs. 7-4 Global Services Customization Guide PLM00091 J

127 Exception and message handling This exceptions displays the following message to the user: Global Services could not authenticate your username or password. Please try again or contact your Global Services administrator. For more information about the GlobalServicesException class and its subclasses, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. Create a custom exception class When a standard GlobalServicesException subclass does not meet your needs, you can subclass the appropriate exception class to provide the needed functionality. The staging-directory\webapp_root\example\exception directory (staging-directory/webapp_root/example/exception directory for UNIX) contains the ExampleGlobalServicesException.java, TextBundle.java, and TextBundleIDs.java files. You can use these files as a starting point for defining your custom exception class. Note To compile a custom exception class, you must have the path to the globalservicescorejar file in the CLASSPATH environment variable. 1. Create an interface class that defines the user interface, for example, the TextBundleIDs class. Create a unique ID string for the exception subclass UI message and a unique ID string for the UI exception title. For example: package example.newexception; public interface TextBundleIDs { static final String IE_NEW_TYPE_OF_EXCEPTION static final String IE_TITLE_NEW_TYPE } = "IEx0007" = "IEx0008" 2. Create an implementation class that defines the UI message and title for your new GlobalServicesException subclass. For example, the TextBundle resource bundle class or some other text message implementation class. Provide a title and a general message that describes the error for the corresponding interface class UI message and UI title IDs. Ensure the message is suitable for an end user on a production system. Do not include the detail that an administrator or developer expects. For example: package example.newexception;. public class TextBundle extends ListResourceBundle { private static final Object[][] CONTENTS = { { TextBundleIDs.IE_NEW_TYPE_OF_EXCEPTION, "This is a general user interface message " + "describing the new exception. " + "Please contact your Global Services administrator." }, { TextBundleIDs.IE_TITLE_NEW_TYPE, "New Type Global Services Error" }, }; } 3. Create a class of string constants to define the name of the text implementation class, the subclass UI message ID, and the UI title ID. This separates your text implementation type from the GlobalServicesException class. For example: package example.newexception;. PLM00091 J Global Services Customization Guide 7-5

128 Chapter 7 Exception and message handling public class NewTypeGlobalServicesExceptionConstants { // Text storage file/class name where user // interface messages are stored. public static String UI_BUNDLE = "example.newexception.textbundle"; // Constant used for the UI message by // ExampleGlobalServicesException subclasses. protected static final String IE_NEW_TYPE_OF_EXCEPTION = TextBundleIDs.IE_NEW_TYPE_OF_EXCPETION; protected static final String IE_TITLE_NEW_TYPE = TextBundleIDs.IE_TITLE_NEW_TYPE; } 4. Create the subclass: a. Create the class as follows: package example.newexception; import com.teamcenter.globalservices.exception;. public class GlobalServicesNewTypeOfException extends GlobalServicesException b. Create a constructor for each GlobalServicesException constructor and call the super class constructor. c. Override the getexceptionid method to return the error ID string for the exception that corresponds to a UI message describing the exception subclass defined in the NewTypeGlobalServicesExceptionConstants class. For example: protected String getexceptionid() { return NewTypeGlobalServicesExceptionConstants.IE_NEW_TYPE_OF_EXCEPTION; } Message localization and logging Global Services provides the TextMessage, MessageDecoderFactory, and MessageDecoder classes that you use to generate messages in the user s locale. Siemens PLM Software recommends that customizations do not directly use the deprecated i18n class for message localization. In order to define a localizable message string, you must create the TextMessage object with a MESSAGE_ID. This parameter, and any TEXT_INSERTS objects defined, cannot be altered after the TextMessage object is created. For more information, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. For information about creating custom or locale specific text bundle classes, see Using text bundles. Global Services uses the Jakarta project log4j package to log messages. A log4j logging object exists for most of (all but interface files and TextBundle files) the Java source files in the Global Services system. A logging object is used to store all exception messages. In your customization, use the logging object instead of if (verbose) System.out.println(Message); statements. The log4j API uses either a properties file or an XML file to determine logging behavior. It allows you to enable and modify message logging at runtime. The log4j architecture uses inheritance in categories to allow you to determine which files generate messages, which types of messages to generate, and where to send the messages. For example, some of the possible message destinations are log files, standard error, standard out, streams, syslogd daemon, and java.io.writer objects. The log4j package provides a series of message levels, which include the following: 7-6 Global Services Customization Guide PLM00091 J

129 Exception and message handling debug, info, warning, error, fatal, and log. Currently, Global Services generates debug type messages for all developer debug statements and error or fatal type messages for all exceptions. Global Services generates error type messages for errors affecting one user and fatal type messages for errors affecting all users. This is subject to change as future releases may require additional message levels. The following is an example of how Global Services uses the log4j package: Create a log object as follows: private static final com.teamcenter.globalservices.log.logger LOG =com.teamcenter. globalservices.log.loggerfactory.getlogger(classname.class()); Generate a debug type log message as follows: LOG.debug("Testing ClassName s debug type of logging"); Generate a warning type log message as follows: LOG.warning("Testing ClassName s warning type of logging"); If an exception affects only one user, generate an error level message as follows: if ( single-user-error ) { GlobalServicesException ie = new GlobalServicesException( message_id, message_class); LOG.error(ie.getTrackingCode + " " + ie.getmessage(), ie); throw ie; } If an exception affects all users, such as a missing entity, generate a fatal level message as follows: if ( all-user-error ) { GlobalServicesException ie = new GlobalServicesException( message_id, message_class); LOG.fatal(ie.getTrackingCode + " " + ie.getmessage(). ie); throw ie; } For more information on the log4j package, visit the Jakarta project log4j Web site at the following URL: Exception coding and logging conventions When Global Services detects an error condition that is related to the Global Services application, you should create and throw a GlobalServicesException subclass exception that describes the error condition. Create the exception and log the detailed error message with its error ID. The error ID is a unique 9-digit number formatted as nnn-nnn-nnn that provides a tracking code for the error in the log file. This number is also sent to the browser to help administrators correlate a user s error message with the detailed exception information in the logs. Creating and logging a Global Services exception Log the exception stack trace. To log the stack traces, do not use the customary exception.printstacktrace method. This method prints the stack trace to standard error. The GlobalServicesException.getStackTrace method is provided as a convenience method that returns the stack trace as a string. Log the string at the time the error is detected and the exception is created. Avoid repeatedly PLM00091 J Global Services Customization Guide 7-7

130 Chapter 7 Exception and message handling printing out the stack trace at various levels. The GlobalServicesException class prints the stack trace only once, unless this option is overridden. Exceptions that affect a single Global Services user should be logged as an error; exceptions that affect all users of the Global Services system should be logged as fatal. The method that creates the exception should throw the parent GlobalServicesException class exception. For example, the following code creates a Global Services exception with a localized string: import com.teamcenter.globalservices.exception; import com.teamcenter.globalservices.exception.globalservicessecurityexception; import com.teamcenter.globalservices.util.msg.messagedecoderconstants; public void somemethod(string str) throws GlobalServicesException { if (some_security_error_condition) { // Create a new Global Services security exception // with a localized string GlobalServicesSecurityException ise = new IntregratorSecurityException( TextBundleIDs.MSG_ID); // log message and stack trace LOG.error(ise.getTrackingCode() + " " + ise.getmessage()); LOG.error(ise.getStackTrace()); throw ase; } } In some cases, you may not have a localized string to provide with the exception. One example of this is when you catch an exception from a data source and want to use that exception information on our Global Services exception. In this case, you can use a common message ID such as TextBundleIDs.EXCEPTION_TAG. For example: // Same imports and static variables as above public void somemethod(string str) throws GlobalServicesException { try { somedatasourcemethod(); } catch (Exception e) { // Create a new Global Services data source // exception with the exception message IntegeratorSecurityException ise = new GlobalServicesSecurityException( TextBundleIDs.EXCEPTION_TAG, e.getmessage()); // log message and stack trace LOG.error(ise.getTrackingCode() + " " + ise.getmessage()); LOG.error(ise.getStackTrace()); throw ise; } } For more information about the GlobalServicesException class, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. Logging non-global Services exceptions When another type of exception is needed to describe an error condition, or is caught in a try-catch construct, log the message with the Exception.toString method. An error ID is not available with non-global Services exceptions. Also print the stack trace to the log, not standard error, using the log4j logging method that takes a throwable object as an argument. For example: try { somemethod(); } catch (Exception e) { // log message and stack trace LOG.error(e.toString(), e); } 7-8 Global Services Customization Guide PLM00091 J

131 Exception and message handling Catching Global Services exceptions at the user interface Global Services action components must catch exceptions and handle them so that appropriate feedback is provided to the user when a problem occurs. This applies not only to exceptions thrown from within the action component themselves (for example, due to incorrect user input), but also the GlobalServicesExceptions class and its subclass exceptions and unchecked exceptions thrown from underlying tiers. Handling these different types of exceptions requires a fair amount of code that is required as part of each action component. To prevent code duplication, the Global Services user interface framework provides the AbstractExceptionHandlerActionComponent abstract action component class that provides standard exception handling. Subclasses of this class typically contain no exception handling at all, instead they let exceptions propagate up to the superclass. If an action component cannot extend the AbstractExceptionHandlerActionComponent class, or if it must handle exceptions in a special way, you must provide its own exception handling. Usually, the exception message is too detailed to be shown to the user. Instead, the exception is logged and a generic error message is created and displayed to the user. The GlobalServiceException class (and its subclasses) is handled differently from other exceptions because it can be localized, and because it contains a unique tracking code. The tracking code can be included in both the generic user message and the log entry, which makes it easier to determine which user operation produced which entry in the log. The following example shows a sample implementation of the action component handleaction method, that performs its own exception handling: public final Option handleaction(actioncontext ctx, Arguments args) throws RequestManagerException { String errortextmsg = null; Locale userloc = // somehow obtain user locale try { // action component business logic goes here return ctx.getoptionset().getoption( success ); } catch (RequestManagerException e) { throw e; // do not catch framework exceptions } catch (GlobalServicesException e) { // Log the exception using default server locale, together with // unique tracking code and stack trace. LOG.error(e.getTrackingCode() + ": " + L10nUtil.getMessage( e.getmessageid(), e.gettextinserts()), e); // Create standardized error message using user locale with a // reference to the tracking code. This is to be displayed to // the user. errortextmsg = L10nUtil.getMessage( TextBundleIDs.AE_ADMIN_REFERENCE_MSG, new Object[]{e.getTrackingCode()}, userloc); } catch (RuntimeException e) // catch any unchecked exceptions { LOG.error(e.getMessage(), e); errortextmsg = L10nUtil.getMessage( TextBundleIDs.EXCEPTION_TAG_0, userloc); } args.setobject( message, "<?xml version=\"1.0\"?><error> <text><![cdata[" + errortextmsg + "]]></text></error>"); return ctx.getoptionset().getoption( failure ); } This example creates a user displayable error message and stores it in an argument slot; however it still must be rendered into a page that can be displayed to the user. This is done by the error_chain response chain in the application map. It is PLM00091 J Global Services Customization Guide 7-9

132 Chapter 7 Exception and message handling therefore necessary for a response chain that uses this action component to declare a failure chain-option as follows: <option id= failure response-chain= error_chain /> This causes the response chain to redirect execution to the error_chain response chain when one of the catch cases in the preceding example is executed. Configuring debug message logging Standard Global Services is configured to log error and fatal exception messages. This configuration is set in the log4j.xml configuration file for your Global Services Web application. You can configure Global Services to log debug or other types of messages using a custom configuration file. The location of the Global Services message log configuration file is set by the LogFileLocation context parameter in the Web Application Manager when you generate the Global Services Web application. You can also use a JMX control to change logging levels. For information about reconfiguring Global Services exception logging, see the Global Services Configuration Guide Global Services Customization Guide PLM00091 J

133 Chapter 8 Using the convenience classes Using the convenience classes BOSClient class methods Traversing business objects Caching the BOSClient object DataObject class Additional convenience methods Sorting search results Supplying sort criteria in the BOD Supplying sort criteria using the user interface Sorting using the comparator utility class PLM00091 J Global Services Customization Guide

134

135 Chapter 8 Using the convenience classes Using the convenience classes You use the convenience classes that Global Services provides to work with Global Services connectors and object data. The BOSClient class is a convenience class that hides the details of linking to connectors and calling individual connector methods. This class supplies the interface from a client (reactor, or Java application) to the business object server of Global Services or, if required, directly to a data source connector. The DataObject class tostring method can be used to generate the XML representation of the data object. The BOSClientFactory class getclient method creates a new instance of a BOSClient interface. Once you create a client instance, you can call any of its methods to interact with the connector. When a method is invoked, the client determines whether a current link to the connector exists. If a link exists, it is used; otherwise, a new link is established. After the link is established, the corresponding connector method is executed. To avoid multiple connections to the same Global Services connector, use the same BOSClient interface for all connections. You must call the remove method to release connectors to data sources in an orderly manner. BOSClient class methods The BOSClient class supports the following methods: Note The execute and compute methods do not support value mapping. Therefore, any execute extension methods do not support value mapping. Method checkformissingattributes compute delete execute Description Determines if a data object is missing attributes defined by the data source. Performs a compute method on the source of this object. This method supports wildcard mapping. Deletes an object from a data source using the connector delete method. This method supports wildcard mapping. Invoked when a connector client calls a specialized connector function. PLM00091 J Global Services Customization Guide 8-1

136 Chapter 8 Using the convenience classes Method expand getattributetextid getbusinessobjectdefinition getmappedobjectname getobjectlist getobjectlistpath getobjecttextid getuserbodir getwildcardinfo insert query remove update Description Expands a relationship maintained by a data source using the connector expand method. This method supports wildcard mapping. Retrieves the text ID associated with an attribute definition. Returns an instance of the BusinessObjectDefinition interface. Use the BusinessObjectDefinition interface to access all of the information in the business object definition configuration files. For more information, see Traversing business objects. Returns the display value associated with the business object. The value is retrieved from the ID map according to the user s current locale setting. Returns a list of strings containing the names of all business objects available for this user. Returns a list of strings containing the names of all business objects available for this user, preceded by the path to the business object definition. Retrieves the text ID associated with a business object. Retrieves the path of the directory that stores the business objects for the current user. Returns the wild card information for the data source. Adds a new object to a data source using the connector insert method. Makes a connection and performs a query on the data source of the object. This method supports wildcard mapping. Releases all connections to all EJBs and the resources they acquired. Modifies existing information in a data source using the connector update method. This method supports wildcard mapping. For a complete listing and description of the BOSClient class methods, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. 8-2 Global Services Customization Guide PLM00091 J

137 Using the convenience classes Traversing business objects The BOSClient class returns a Java object hierarchy that contains all of a business object s data. This allows the BOSClient class to interrogate the business object locally. Use the BOSClient class getbusinessobjectdefinition method to retrieve and instance of the BusinessObjectDefinition interface. You can access all of the configuration information for the business object with this interface. Global Services provides additional common utility methods in the ObjectDefinitionUtil class for querying the business object. The DefinitionVisitor class defines a visitor for business object definitions. The visitor pattern allows you to add methods to an object structure without changing the element classes of the object structure. The BusinessObjectDefinition interface provides the accept method that takes the visitor and applies the visit method to itself. The accept methods also traverses the object hierarchy. The methods perform a depth first traversal of the business object definition. You can extend this class to perform visit methods for parts of a business object. The following DefaultValueExample.java file shows how to create visitors to get attributes with default values: import com.edsplm.plmi.bod.attributedefinition; import com.edsplm.plmi.bod.businessobjectdefinition; import com.edsplm.plmi.bod.datasourcedefinition; import com.edsplm.plmi.bod.definitionvisitor; import com.edsplm.plmi.bod.staticattributedefinition; import com.teamcenter.globalservices.bos.bosclient; import java.util.*; public class DefaultValueExample { public static class DefaultValueVisitor extends DefinitionVisitor { List attributelist_ = new ArrayList(); public void visit(attributedefinition attrib) { if (attrib instanceof StaticAttributeDefinition && ((StaticAttributeDefinition) attrib).getdefaultvalue()!= null ) { attributelist_.add(attrib); } } public List getlist() { return attributelist_; } public void reset() { attributelist_.clear(); } } public static void main(string[] args) throws com.teamcenter.globalservices.exception.globalservicesexception { BusinessObjectDefinition bod = new BOSClient("test", "test1234").getbusinessobjectdefinition("employee"); System.out.println("\n\nAttributes w\default Values in business object definition:"); DefaultValueVisitor defvalvisitor = new DefaultValueVisitor(); bod.accept(defvalvisitor); List attrswithdefaultvals = defvalvisitor.getlist(); Iterator attriterator = attrswithdefaultvals.iterator(); while (attriterator.hasnext()) { StaticAttributeDefinition attrdef = (StaticAttributeDefinition) attriterator.next(); System.out.println("attribute: " + attrdef); } System.out.println("\n\nAttributes with Default Values in the first data source:"); attriterator = getdefaultvalueattributes(bod.getprimarydatasource()).iterator(); while (attriterator.hasnext()) { StaticAttributeDefinition attrdef = (StaticAttributeDefinition) attriterator.next(); System.out.println("attribute: " + attrdef); } } /** * A more compact and elegant solution using an anonymous inner class. * This method returns all of the attributes with default values within * the given data source. */ public static List getdefaultvalueattributes(datasourcedefinition source) PLM00091 J Global Services Customization Guide 8-3

138 Chapter 8 Using the convenience classes } { } final List attriblist = new ArrayList(); source.accept(new DefinitionVisitor() { public void visit(attributedefinition attrib) { if (attrib instanceof StaticAttributeDefinition && ((StaticAttributeDefinition) attrib).getdefaultvalue()!= null) { attriblist.add(attrib); } } }); return attriblist; There are two methods for configuration a connector when name and value pairs are insufficient. You can escape XML and put it in the value as shown in the following example: <box-config name="bcname"> <util:param value="<test1><test2>data</test2></test1>" name="test1"/> </box-config> You can generated this example value using Java Architecture for XML Binding (JAXB) as follows: param.setvalue("<test1><test2>data</test2></test1>"); Many XML editors escape XML for you if you put it in an attribute. You can also put the name of another configuration file in a parameter and use the Global Services datastore to access the file. For example: <box-config name="bcname"> <util:param value="/config/configfile2" name="config-data"> </box-config> For more information, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. Caching the BOSClient object Global Services provides a client object caching feature that can improve performance and allows sharing of EJB connectors between handlers in the same user session. This feature is applicable only to HTTP requests. By default, this feature is enabled. To disable this feature, create a thin client customization and in your custom-application_app_map_xml file, override the globalservices.client.caching application map tag to change the attribute value to false. For information about thin client customization contact GTAC. DataObject class The DataObject class provides a generalized mechanism for passing data object information within the Global Services environment. Information associated with an object is modeled within the data object as attribute name-value pairs and additional properties. Among these additional properties are the attribute type and default display information. The amount of additional information depends on the data source. The DataObject class has the following methods: 8-4 Global Services Customization Guide PLM00091 J

139 Using the convenience classes Method clone getattributes getbodname getdatasourcename getwhereclause setbodname setdatasourcename setwhereclause Description Makes a replica of the data object with a copy of the attributes. Returns the list of attributes or column values that this data object comprises. Returns the name of the business object definition that contains the metadata about this business object. Returns the name of the data source from which this data originated. Returns the where clause representing the object or row that designated the object. Sets the name of the business object definition which contains the meta data about this business object. Set the name of the data source from which this data originated. Set the where clause representing the object or row that designated the object. For a complete listing and description of the DataObject class methods, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. Additional convenience methods Global Services also provides the Attribute class that includes convenience methods, such as: clone Returns a duplicate of the attribute. getname Returns the name of the attribute. getsegmentname Returns the name of the segment from the business object definition in which this attribute is defined. gettype Returns the data type of this attribute. getvalue Returns the value of the attribute. getvalueasobject Returns the value as an object of the appropriate type. PLM00091 J Global Services Customization Guide 8-5

140 Chapter 8 Using the convenience classes setname Sets the name of this attribute. setsegmentname Sets the name of the segment from the business object definition in which this attribute is defined. settype Set the data type of this attribute. setvalue Sets the value of this attribute. Additionally, some convenience methods are available in the DataObjectDecorator class: add Adds an attribute to the decorated data object. contains Determine if the named attribute exists within this decorated data object. get Returns the named attribute from the decorated data object. getattributenames Returns a list of attribute names that exist in the decorated data object remove Removes the named attribute from the decorated data object. The DataObjectFactory class contains factory methods for creating DataObjects, Attributes, and DataObjectDecorators instances: getattribute Returns a new instance of the Attribute interface. getdataobject Returns a new instance of the DataObject interface. getdataobjectdecorator Returns a decorator around either a new or existing DataObject instance. The DataObjectUtil class provides utility methods for data objects and the AttributeUtil class provides utility methods for attributes. For a complete description of these classes and their methods, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link. 8-6 Global Services Customization Guide PLM00091 J

141 Using the convenience classes Sorting search results Global Services provides several utility classes that you can use to implement custom sorting of search results. This discussion describes these utility classes and provides examples showing how to use them. To sort search results, you must specify the sort order (ascending or descending), and you must assign a priority to the attributes. Also, you must decide if you want to specify these criteria at the user interface level or in the business object definition (BOD). The value of the sort priority entry contains an integer specifying which attributes are sorted first. The attributes are sorted in the order specified by the sort priority values. An attribute with a sort priority value of 1 is sorted first, a value of 2 is sorted second, and so on. Attributes with a type element in the business object definition are sorted according to that type value. Attributes without a type element use a string type sort. For example, when sorting an attribute containing integers, the sort is done using a numeric comparison when the type is set to integer in the type entry of the attribute. If the type is not set in this case, the sort is done using string as the type. The type being used makes a difference for an integer attribute when the values 9 and 10 are compared. Using an integer sort, 10 is the larger number. However, when a string sort is done, the first characters are compared and 9 is bigger than the 1 in the number 10. Therefore, 9 is the bigger number. Global Services provides three utility classes for performing sorts. The following information describes sorting using the DataObjectSortUtil class and the last process describes sorting using the DataObjectComparator utility class and the value of its isreversecomparison argument. In most cases, however, you should use the DataObjectSortUtil class to perform your sorts. Always call the desired sort method after your query results have been returned. This allows multiple data source and multiple segment objects to be sorted without regard to where they come from. Also, you must sort before the results are displayed to the user. For more information about these classes, see the online class documentation for the com.teamcenter.globalservices.data package (Global Services Javadoc) available from the Global Services Developer Info link. Supplying sort criteria in the BOD To use the BOD to specify the sort criteria, you must call the setbosortcriteria method of the DataObjectSortUtil class. This method looks for the attributes with a sort priority specified by finding the attributes with a sort-key element. Any attribute defined in the business object definition can be used as a sort field. The attributes can have a hidden element value of true. Specify the sort order using the sort-direction element. It is defined once for the entire business object. For example, you can define an ascending sort order for a business object as follows: <business object description name="department"> <label ID="Department.name"/> <sort direction>ascending</sort direction> <data-source name="department">. Specify the sort priority using the sort-key element. For example: <attribute name="lastname"> PLM00091 J Global Services Customization Guide 8-7

142 Chapter 8 Using the convenience classes <label ID="Employee.attr.LastName" default="last Name"/> <name-on-source>lastname</name-on-source> <search able>true>/search able> <sort-key>1</sort-key> </attribute> The following pseudo code shows how you read the sort criteria from the business object and perform the sort: DataObjectSortUtil go_sort = new DataObjectSortUtil(); String bo_directory = base business object directory String bo_name = name of business object definition Vector records = Vector of GenericObjects // get sort criteria from business object definition if (get sort criteria from business object definition) { go_sort.setbosortcriteria(bo_name, bo_directory); } else { // get the sort criteria some other way } go_sort.sort(records); The following example shows the GlobalServicesMsgResult.xml business object definition file. The sort feature elements are in bold. <?xml version="1.0" encoding="utf-8" standalone="yes"?>. <business-object-definition name="globalservicesmsgresult" xmlns:xsi=" xmlns:conn=" xmlns:util=" xsi:nonamespaceschemalocation="business-object-definition.xsd" xmlns=" <sort-direction>ascending</sort-direction> <data-source name="globalservicesmsgresult"> <data-segment name="result"> <conn:data-source-spec JNDI-name="TcGSJDBCBox" config-name="jdbcmessagebox"/> <class-name>reactorresult</class-name> <relation name="messagebyid"> <result-name>globalservicesmessage</result-name> <util:where-clause>messageid = this.messageid </util:where-clause> </relation> <attribute name="reactorname"> <search-able>true</search-able> <sort-key>2</sort-key> </attribute> <attribute name="delivereddate"></attribute> <attribute name="result"> <search-able>true</search-able> <sort-key>1</sort-key> </attribute> <attribute name="sequenceno"> <name-on-source>sequencenumber</name-on-source> </attribute> <attribute name="processedcount"> <type>int</type> <sort-key>3</sort-key> </attribute> <attribute name="messageid"> <primary-key>true</primary-key> <link name="all messages" href="search?object=globalservicesmessage&fields=0"> </link> <link name="message" href="expand?object=globalservicesmsgresult&relation=messagebyid&?> &Fields=1&FieldName1=MessageID&FieldValue1=this.MessageID"> </link> <link name="republish Message" href="msgserver-republishmsg?reactor=this.reactorname&message_id= this.messageid"> </link> <link name="republish Reactor" href="msgserver-republishreactor?reactor=this.reactorname"> </link> </attribute> </data-segment> </data-source> 8-8 Global Services Customization Guide PLM00091 J

143 Using the convenience classes </business-object-definition> For more information on business object definitions, see the Global Services Configuration Guide. Supplying sort criteria using the user interface You can also allow the user to set the sort criteria at the user interface. The sample Global Services user interface search form has a sort order field and sort priority fields (one for each searchable attribute). The search form adds the sort field information to the URL that it generates. In the URL, the SortOrder field defines the sort direction and the SortValueX fields define the sort priority. Your custom user interface can use the search functionality of the standard Global Services search link (action handler). This action handler returns sorted results when sort fields are present in the URL you supply to it. The following is a sample URL containing sort criteria: &?>&FieldValue1=&SortValue1=&OriginalVal1= &?>&FieldName1=DEPARTMENT_NUMBER&FieldValue2= &SortValue2=1&OriginalVal2=&FieldName2=DEPARTMENT_NAME &?>&FieldValue3=&SortValue3=2&OriginalVal3= &FieldName3=MGRNO&FieldValue4=&SortValue4= &?>&OriginalVal4=&FieldName4=ADMRDEPT&MaxObjects=50 &SortOrder=ascending You can implement custom sort functionality with either an ascending or a descending sort order. To use the DataObjectSortUtil class to perform an ascending sort, specify the sort order parameter as ascending. To use the class to perform a descending sort, you must specify the sort order parameter as descending. The following pseudo code shows how you specify the sort order using the DataObjectSortUtil class: if (sort order == "ascending") { go_sort.setsortorder("ascending"); } else // sort descending { go_sort.setsortorder("descending"); } You can also implement custom sort functionality with attribute sort priorities. The following pseudo code shows how you specify sort priorities using the DataObjectSortUtil class: for (each field to sort on) { // field_name is the name of the field to sort on // sort_priority is the integer value representing // the priority the field receives addsortfield (field_name, sort_priority); } After specifying the sort order and the sort field priorities, the sort is done as follows: // sort the records in the proper order using the // DataObjectSortUtil class go_sort.sort(records); PLM00091 J Global Services Customization Guide 8-9

144 Chapter 8 Using the convenience classes Sorting using the comparator utility class Global Services provides three utility classes for performing sorts. Global Services provides a utility class that you can use to compare DataObject instances. To compare attributes in two DataObject instances for sorting, you can use the DataObjectComparator class to sort the items in ascending order or, with the isreversecomparison argument set to TRUE, to sort in descending order. The DataObject sort and comparator classes are in the com.teamcenter.globalservices.data package. The DataObjectComparator class takes a SortedMap list containing a list of attributes to compare as a constructor parameter. You call the desired compare method to compare the DataObject attribute values contained in the SortedMap list of attributes. DataObjectComparator class can be used in any way a java.util.comparator class can be used. The following example shows how to use these comparator classes: Vector records = vector of GenericObjects to sort SortedMap sort_fields = fields to sort in order of sortkey priority Comparator compare = comparator used for comparing two DataObjects if (sort order == "ascending") { compare = new DataObjectComparator(sort_fields, 0); } else // sort descending { compare = new DataObjectComparator(sort_fields, 1); } // sort the records using the proper order sort (records, compare); 8-10 Global Services Customization Guide PLM00091 J

145 Chapter 9 Creating a custom security service Creating a custom security service PLM00091 J Global Services Customization Guide

146

147 Chapter 9 Creating a custom security service Creating a custom security service This procedure provides the tasks required to customization aspects of the single sign-on credential service. Global Services provides two built-in credential services; a lightweight directory access protocol (LDAP) service and an XML file-based service. You may use either of these built-in services or you can create a custom credential service if your site already has a single sign-on credential service with its own API. You create a custom credential service in Global Services using a new Java class. A site can plug in any class that meets the SecurityInfoService Java interface. 1. Create a Java class and ensure that the application server CLASSPATH includes the new class name. Define your new class as a credential service in the SecurityServices.xml file. This file is located in the security folder of the Global Services datastore. For information about the Global Services datastore, see the Global Services Configuration Guide. For example: <security-service name="wsl" enabled="true"> <custom-security-info-service class-name="com.amt.security.wslsignoncredentialservice"> <config:instantiate-object class-name="com.amt.security.wslsignoncredentialservice"> <config:constructor-description class-name="com.amt.security.wslsignoncredentialservice"/> <config:method-description name="setparameter"> <config:argument-description class-name="java.lang.string"> <config:value-description class-name="java.lang.string"> <config:value>wsl-host</config:value> </config:value-description> </config:argument-description> <config:argument-description class-name="java.lang.string"> <config:value-description class-name="java.lang.string"> <config:value>wsl.amt.com</config:value> </config:value-description> </config:argument-description> </config:method-description> <config:method-description name="setparameter"> <config:argument-description class-name="java.lang.string"> <config:value-description class-name="java.lang.string"> <config:value>access-type</config:value> </config:value-description> </config:argument-description> <config:argument-description class-name="java.lang.string"> <config:value-description class-name="java.lang.string"> <config:value>secure</config:value> </config:value-description> </config:argument-description> </config:method-description> </config:instantiate-object> </custom-security-info-service> </security-service> This constructs a WLSSignOnCredentialService instance and calls the setparameter method twice on the instance to set the wsl-host and access-type parameter values. 2. The parameter values are passed to the object as strings as defined by the com.teamcenter.globalservices.util.parameterizable interface. To pass the PLM00091 J Global Services Customization Guide 9-1

148 Chapter 9 Creating a custom security service values to the constructor, nest the argument-description elements in the constructor-description element instead of in separate method-description elements. For more information about the following classes, see the online class documentation (Global Services Javadoc) available from the Global Services Developer Info link: com.teamcenter.globalservices.security.securityinfoservice com.teamcenter.globalservices.util.parameterizable 9-2 Global Services Customization Guide PLM00091 J

149 Chapter 10 Tailoring a BPEL process Tailoring a BPEL process How BPEL framework works Create and deploy a Web service for BPEL Best practices Adding a pre-export step to the data transfer process Create a BPEL project Add a new process step Package and deploy the process Deploy a custom BPEL process to Global Services PLM00091 J Global Services Customization Guide

150

151 Chapter 10 Tailoring a BPEL process Tailoring a BPEL process The Global Services BPEL framework simplifies the transaction management process for data transfers between Teamcenter and other products. BPEL eliminates the need for multiple Java Messaging Service (JMS) queues and intermediate Java services. As a result, transaction management does not have to be done through transaction tables. This simplifies tailoring processes because you can easily add more functionality into a BPEL process. The BPEL framework helps in: Eliminating the use of developer-created threads. Eliminating the use of transaction tables. Optimizing the required number of JMS queues. You can also create a Web service that accesses the BPEL framework. How BPEL framework works The following figure shows the BPEL framework workflow for the BOM transfer process. 1. BPEL Engine runs the BPEL process that contains steps of the transfer workflow (export objects, data mapping, import objects, confirm export, stub replication notification, ownership transfer). 2. Major steps in the BPEL process (Transfer workflow) start Axis2 Web services that execute PLMXML extract, PLMXML load, file download, and file upload. PLM00091 J Global Services Customization Guide 10-1