Using ObjectsIncorporating Objects in Application FilesYou use objects in Tango by adding Create Object Instance and Call Method actions to application files. You can also use the <@CREATEOBJECT> and <@CALLMETHOD> meta tags to create and use object instances in Tango. This alternative is recommended for advanced users. For more information, see the Meta Tags and Configuration Variables manual. The basic concepts of objects in Tango are covered in the previous chapter. This chapter focuses on the procedure and details of using objects. The topics covered in this chapter include:
Preparing to Use Objects in TangoPlanning to Use an ObjectHere are some issues to be aware of before using objects with Tango application files:
|
|||||||
For more information, see "Object Types Supported in Tango". |
Installing an ObjectThe following are some guidelines for installing objects before developing and deploying Tango application files:
Local and Remote Machines |
||||||
Tango also supports COM objects on the Windows platform. For more information, see the Tango 2000 User's Guide for Windows. |
The different object types that Tango supports are JavaBeans and Tango class files. In most cases, you use objects installed on the local machine (same machine as Tango Server). If your deployment machine is not the same as your development machine, you need to install the objects on both machines. Depending on the object type, you may also be able to use objects installed on remote machines. When deciding which machine to use, consider load balancing and fault tolerance issues.
|
||||||
For more information, see "Setting Search Paths for Tango Class Files" and "Objects". |
|||||||
For more information, see "TCFSearchPath" in the Meta Tags and Configuration Variables manual. |
Overview of Using Objects in TangoYou use an object in Tango by adding Create Object Instance and Call Method actions associated with an object to your Tango application file or Tango class file. The procedure can be broken down into three steps. The following steps allow you to use the graphical interface of Tango Editor to develop Tango application files with objects. Advanced Tango users may want to use Tango meta tags to create and use object instances. See the Meta Tags and Configuration Variables manual for details. Step 1: Add Objects to the Objects Workspace |
||||||
For more information, see "Adding an Object to the Objects Workspace". |
You can only use objects that are visible in the Objects Workspace. If the objects you want to use are not there, you have to add them first. |
||||||
For more information, see "Viewing Object Information in the Objects Workspace". |
Step 2: Add Create Object Instance ActionsTango does not use the objects you see in the Objects Workspace directly; it uses instances created from these objects. The instances created from these objects are called "object instances", or simply "objects". |
||||||
For more information, see "Using Available Object Instances". |
Before you can call a method involving an object in a Tango application file or Tango class file, an object instance must be available. |
||||||
For more information, see "Adding a Create Object Instance Action". |
Depending on the circumstances, you may have to create an object instance with a Create Object Instance action. Step 3: Add Call Method Actions |
||||||
Once an object instance is available, you can incorporate its methods into your Tango application file or Tango class file by adding Call Method actions associated with this object. Adding an Object to the Objects WorkspaceIf the Workspace is not visible on your screen, choose Workspace from the Windows menu. To view the Objects Workspace, click the Objects tab in the Workspace.
JavaBeans in the Objects WorkspaceTo add a JavaBean to the Objects Workspace
Tango Class Files in the Objects WorkspaceTo add a Tango class file to the Objects Workspace
Removing an Object From the Objects WorkspaceIf there are objects in the Objects Workspace that you do not need, you can remove them. When you remove an object from the Objects Workspace, you are not deleting the object from your machine, just from the Objects Workspace. You can easily add the object to the Objects Workspace again, when you need it. If you have already incorporated an object in a Tango application file or a Tango class file, removing the object from the Objects Workspace does not affect the application file or the Tango class file. To remove an object from the Objects Workspace
Viewing Object Information in the Objects WorkspaceIn the Objects Workspace, you can view information on objects by successively expanding items at each level. The information you get from the Objects Workspace includes the following: |
|||||||
Additional object information is available to you in the Object Properties window. For further information about objects, consult the documentation supplied by the respective object vendors. The following is an example of the Objects Workspace with expanded items:
To view information on an object
|
|||||||
Attributes FolderIn some cases, the Attributes folder appears under an object. This folder contains the getter and setter methods of the object. The getter and setter methods let you get and set attributes (also known as properties or data members). Unlike most methods of an object, getter and setter methods are very simple methods:
Object PropertiesThe Object Properties window displays a summary of the information about the object you select. You cannot change the information in this window.
To view object propertiesGeneralThe General section of the Object Properties window displays the following information: DetailsThe Details section of the Object Properties window displays attributes and their associated values. The attributes displayed in this section depend on the object type and the object. For a detailed description of the attributes, refer to the documentation from the object vendor. Caching and Refreshing of Object InformationWhen you add an object to the Objects Workspace, Tango stores the introspection information about the object--including methods and parameters--in the Object Cache file in the Support Files folder within the Tango 2000 folder. The cache offers you some advantages:
Developers of objects sometimes improve the design of their objects. If you want to update the object information in the cache, you can refresh the objects as follows:
Adding a Create Object Instance Action |
|||||||
For more information, see "Adding an Object to the Objects Workspace".. |
Before you add a Create Object Instance action to your Tango application file or Tango class file, make sure the object from which you want to create an object instance is available in the Objects Workspace. A Create Object Instance action is a Tango action. The action icon is available on the Actions palette. The procedure for adding a Create Object Instance action is the same whether you are working with a JavaBean or Tango class file. To add a Create Object Instance action
|
||||||
For more information, see "Completing the Create Object Instance Action". |
|
||||||
Shortcut to Adding a Create Object Instance Action
An alternative approach to adding a Create Object Instance action from the Actions palette is to do it directly from the Objects Workspace. This procedure is a slight modification of the one described on Adding a Create Object Instance Action. Skip the step involving the Create Object Instance action icon. Just drag the object you want to use from the Objects Workspace to the location you want in the application file or Tango class file. Completing the Create Object Instance Action
The Create Object Instance action window contains important information about a Create Object Instance action. It allows you to view and edit this information. You can open the Create Object Instance action window by doing one of the following: |
|||||||
For more information, see "Adding a Create Object Instance Action". |
|||||||
For more information, see "Shortcut to Adding a Create Object Instance Action". |
The title of the Create Object Instance action window consists of the name of your Tango application file, followed by the name of the action, separated by a colon. |
||||||
The default name of the Create Object Instance action is Create_Object_Instance. You can change it in the application file window. There are several sections to the Create Object Instance action window: object name, object instance variable, instance, and expiry URL. Object NameThis is the field next to the Create Object Instance action icon. The object name is the name of the object from which you create the object instance. If no object has been assigned to this action, the field displays the message Drag an object from the Workspace. Object Instance VariableThis section sets the name and the scope of the variable that refers to the object instance once it is created. Scope |
|||||||
You can select a scope from the pop-up menu, or enter a custom scope. The default is Local. When you select a scope, consider how you plan to use the variable. For example, you are using the object instance to calculate interest based on principle and interest rate, and you want to get the balance later, in another application file. In this case, you should select the User scope instead of the Local scope, because the User scope makes the variable available beyond the execution of the current application file. NameEnter the variable name in this dialog box. The name that you enter in this box becomes available in the pop-up menu in the Object Instance Variable section of Call Method action windows in the same Tango application file or Tango class file. InstanceThe options in this group are only available if you are editing Tango application files or Tango class files created on a Windows machine that use COM objects. COM objects are not available on the Macintosh platform, but you can still edit application files and class files that were created on Windows to use COM. Create New Object |
|||||||
Create New Object is the default option. Tango Server creates a new instance of the object when the application file is executed. The new instance exists until the expiry time is reached--which is determined by the variable scope that you specify in the Object Instance Variable section--or until it is purged with a <@PURGE> meta tag. Get Existing ObjectIn some special cases, you may want Tango to connect to an object instance that is already existing, instantiated by the operating system of your machine, independent of your Tango application file. If you are familiar with the way this process works and you want to use the object instance in this manner, you can make this selection. Currently, Tango supports this feature only in COM objects. If you are using a JavaBean or a Tango class file, this selection is disabled. If the object you specify is not registered properly as a global COM resource when Tango Server executes the Create Object Instance action, Tango Server generates an error. Initialization StringThis feature allows you to bring up COM objects in some initialized state, as implemented by the referenced moniker. (A referenced moniker is a term used with COM objects; it is essentially a string of characters in a special format for creating initialized COM objects. See your COM object documentation for details.) Specifying an initialized state can combine several actions into one, and thus save development time. An example of using a referenced moniker is to specify an action based on a spreadsheet file. When Tango Server executes this initialized object instance, it opens the spreadsheet program and the spreadsheet file, lets the spreadsheet program perform its operations and returns the result to Tango. Currently Tango supports the use of initialization string only in COM objects. If the instance you are creating is from a JavaBean or a Tango class file, the field is disabled. You can do one of the following with the Initialization String text box:
Username and PasswordBy default, a COM object uses the username and password of your Tango Service login. However, you have the option to specify a different username and password for this COM object. The Username and Password text boxes allow you to enter optional security information for this COM object. Both text boxes accept meta tags and are encrypted in the Tango application file or Tango class file. Username and password fields are limited to 128 characters. Currently, Tango supports the use of username and password only in COM objects. Expiry URLWhen the object instance expires, Tango destroys the instance. You can direct Tango Server to perform application-specific cleanup operations prior to the destruction of the instance. Enter either a valid URL or one or more meta tags that evaluate to a valid URL. The URL must be a complete HTTP URL that Tango Server can access. For example: http://www.example.com/mycleanup.taf?object=myobject Adding a Call Method ActionBefore you add a Call Method action to your Tango application file or Tango class file, make sure the following conditions are met: |
|||||||
For more information, see "Adding an Object to the Objects Workspace", "Using Available Object Instances", and "Completing the Create Object Instance Action". |
A Call Method action is a Tango action. The action icon is available on the Actions palette. The procedure for adding a Call Method action is the same whether you are working with a JavaBean or Tango class file. To add a Call Method action
|
||||||
For more information, see "Completing the Call Method Action". |
|
||||||
Shortcut to Adding a Call Method Action
An alternative approach to adding a Call Method action from the Actions palette is to do it directly from the Objects Workspace. This procedure is a slight modification of the one described on Adding a Call Method Action. Skip the step involving the Call Method action icon. Just drag the method you want to use from the Objects Workspace to the location you want in the application file or Tango class file. Completing the Call Method Action
The Call Method action window contains important information about a Call Method action. It allows you to view and edit this information. You can open the Call Method action window by doing one of the following: |
|||||||
For more information, see "Shortcut to Adding a Call Method Action". |
The title of the Call Method action window is the name of your Tango application file, followed by the name of the Call Method action, separated by a colon. |
||||||
You can change the name of the Call Method action in the application file window. The following is an example of the Call Method action window: There are several sections to the Call Method action window: object/method name, object instance variable, result variable, and parameter list. Object/Method NameThis is a non-editable field at the top of the window, next to the Call Method action icon. The object/method name consists of the name of the object, followed by the name of the method, separated by a dot. If no method has been assigned to this action, the field displays the message Drag a method from the Workspace. Object Instance VariableThis section allows you to specify the object instance you want to use in your Call Method action. You must have created the object instance in a Create Object Instance action and given it a variable name. Before you complete the information in this section, you need to know the following: You can view this information by double-clicking the appropriate Create Object Instance action. From the Scope and Name pop-up menu/text fields, select the appropriate items or enter them.
ExampleThe Create Object Instance action creates an object instance, MyObjectInstance, from the object, MyObject; the variable to which this instance is assigned is MyVariable, in Local scope. To specify a Call Method action using this object instance, drag MyObject in from the Objects Workspace, and specify MyVariable, in Local scope, in the Object Instance Variable section of the Call Method action window. Result VariableThe Call Method action may generate a result. The data type of the return result is indicated in parentheses after the Put Result into Variable title. An example is (bool). |
|||||||
For more information, see "Viewing Object Information in the Objects Workspace". |
This information is also shown in the Objects Workspace.
If you plan to use the result later in your application file, put the return result into a variable. From the Scope and Name pop-up menu/text fields, select the appropriate items or enter them. ExampleYou are using the Interest Calculator object to calculate the interest on a customer account. When you get the result of the calculation, you can store it in a variable called Interest. When you need to use this result later to present a statement on a Web page, refer to the Interest variable. Parameter ListA parameter allows a Tango application file to exchange data with an object. The exchange can be an input (passing data from the application file to the object), output (passing data from the object to the application file), or input/output (passing data from the application file to the object and putting the new value from the object in the original variable). NameThis column shows the parameter names, and whether a parameter is an input, output, or input/output parameter. The following icons are used: |
||||||
Parameter names are also listed in the Objects Workspace. If you want to change a parameter name, do it in the Objects Workspace. After the change, Tango updates the Call Method action window. (You have to close and reopen the Call Method action window to see the new name.) TypeThis column shows the data type of each parameter. There are two categories of data types: |
|||||||
For more information, see "Viewing Object Information in the Objects Workspace".. |
FormatThis column shows the format of a parameter. A parameter has one of two formats: Variable and Value.
When you click the Format column of a parameter, the format for this parameter becomes enclosed in a pop-up menu. If the parameter is an input parameter, you can select Variable or Value; otherwise, it can only be Variable. ValueThis column shows the value or variable of a parameter. You can change the values and variables in this column. |
||||||
Incl. EmptyThis column is enabled for optional parameters. With an optional parameter, you can specify whether or not to include this parameter in a Call Method action. Only COM objects can have optional parameters. Using the Objects Loop ActionIn some cases, a method call returns several items collected into an object, called a collection object. The purpose of a collection object is to allow you to work with all the items or selected items in the collection, one by one, in a loop action. |
|||||||
For more information, see "Repeating Actions (Loop Actions)".. |
The Objects Loop action is a loop action which works similarly to the For Loop action. You can have nested Objects Loop actions (an Objects Loop action within an Objects Loop action). The Objects Loop action can work with appropriate objects retrieved from JavaBeans. Example of Using an Objects LoopSuppose there is a group of related objects that allow you to look up and present all the product names in a product category. This involves the following objects:
You first create an object instance of the ProductCategory object, using a Create Object Instance action. Then use a Call Method action to call getProduct and to put the result of this method--the ProductCollection collection object--into variable x. |
||||||
See an example of the Objects Loop action dialog box on The Objects Loop action dialog box appears:. |
Now you start an Objects Loop action to work with the items in the collection object, which is the result of the aforementioned Call Method action. This Objects Loop action uses the variable x to refer to the ProductCollection collection object and the variable y to refer to each individual item in the collection. Place a Call Method action inside the Objects Loop action, to call getName, so that it to looks up and presents the items in ProductCollection. Use the variable y as the object instance variable to refer to the current item in the collection. The following diagram shows how you might incorporate a sequence of actions in you Tango application file to use an objects loop:
Using an Objects LoopUsing an objects loop requires a sequence of actions, generally including at least a Create Object Instance action, a Call Method action, and an Objects Loop action. The precise requirements depend on the collection object you use and what you want to do with it. Refer to the documentation from your object vendor for details. |
||||||
For more information, see "Using Available Object Instances". |
The heart of the sequence is the Objects Loop action, which works on a collection object. Typically you get a collection object as the result or an output from a Call Method action, which in turn needs to use an available object instance. |
||||||
For more information, see "Adding a Create Object Instance Action". and "Adding a Call Method Action". |
The use of Create Object Instance action and Call Method action is covered in other sections. This section focuses on using the Objects Loop action. To specify an objects loop for a collection object
|
Copyright © 1999, Pervasive Software. All rights reserved.