Core Library Tags
To use the Info*Engine tags, include the taglib directive, which identifies the tag library and provides a prefix for uniquely identifying the tags on the page. For example, to use the core Info*Engine tags and identify them by the ie prefix, include the following directive:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
The syntax for the tag assumes that you have specified the ie prefix in the taglib directive. If you specify a different prefix, use the prefix you specified in place of ie in the tag syntax.
displayResource
The displayResource tag extracts a string from a group created with the Get-Resource webject or directly from a resource bundle. The tag then replaces one variable place holder in the extracted string (if you supply replacement text) and displays the resulting string.
This tag is provided as an alternative to using the Display-Resource webject.
|
|
Tags do not support multivalued attributes. Therefore, if an extracted string contains more than one variable place holder, you cannot use the displayResource tag to properly display the resulting string. Instead, you must use the Display-Resource webject.
|
Syntax
<ie:displayResource bundle="bundle_name"
groupIn="group_name"
key="bundle_key"
param="text"/>
Attribute Descriptions
Require Attributes: bundle or groupIn, and key.
bundle
Indicates the Java class resource bundle from which the localized string is extracted. This attribute is required if no groupIn attribute is supplied.
groupIn
Indicates the bundle group from which the message is to be extracted. This attribute is required if no bundle attribute is supplied.
key
Indicates the key into the resource bundle. This can be either the number or the actual Java variable reference name. This is a required attribute.
param
Specifies text to be inserted into a localized message that contains a variable place holder. For example, if the extracted string contains a variable place holder for text, such as:
The validation of user "{0}" has failed.
You can include the text that replaces {0} in the param attribute. For example, assume that you include the following attribute:
param="abc123"
Then, the resulting string becomes:
The validation of user "abc123" has failed.
This is an optional attribute. If the attribute is omitted, then the substitution does not occur.
If an extracted string contains more than one variable place holder, you must use the Display-Resource webject rather than this tag.
Example
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The displayResource tag in the example specifies that the messages associated with line 19 of the resource bundle retrieved using the Get-Resource webject be displayed:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:webject name="Get-Resource" type="MGT">
<ie:param name="BUNDLE"
data="com.infoengine.util.IEResource"/>
<ie:param name="GROUP_OUT" data="IEResource"/>
</ie:webject>
<b>
<ie:displayResource groupIn="IEResource" key="19"/>
</b>
failure
The failure tag allows you to supply code for failure processing within a unit. The code between the start and end failure tag executes only when the body of the unit does not complete successfully. You can include multiple failure tag blocks in a unit:
• To include general failure processing, specify the failure tag with no attributes.
• To include code for processing a specific exception, specify the failure tag with the name of the exception in the exception attribute.
If you do not include a failure tag block for processing an error that occurs in the body of a unit, no failure processing occurs and the page continues to be processed following the unit end tag.
You nest this tag in unit tag blocks. To provide failure code sets for specific errors, you can specify multiple failure tag blocks. On each failure tag, you can name a specific error in the exception attribute. You can nest multiple webject, task, unit, and parallel tags in this tag block.
To manage exceptions within a
failure tag block, you can include the Throw-Exception webject. For more information, see
Management Webjects. Including this webject is a way to propagate (rethrow) exceptions that are caught by
failure tags. You can simply add the following in the block:
<ie:webject name="Throw-Exception" type="MGT"/>
Including this webject causes the caught exception to be rethrown. Rethrowing exceptions is useful when unit blocks are nested or when you want exceptions caught in a unit block to be passed on to the page.
If an exception occurs in a failure tag block, the exception is propagated outside the unit block.
Scriptlets that are nested in unit, init, success, and failure tag blocks are not processed on JSP pages the same way they are processed in the Info*Engine task processor. Use the following guidelines to determine when you can nest scriptlets in these tags:
• You can nest scriptlets within tag blocks in a standalone task.
• You should not nest scriptlets in any tag block on a JSP page. Instead, create standalone tasks that contain the scriptlets. You can execute these tasks from the JSP page by using the Info*Engine task tag.
For additional information about scriptlets, see
Scriptlets.
|
|
Embedded HTML is not supported within failure tags in JSPs.
|
Syntax
<ie:failure exception="exception_name">
.
. (webject, task, unit, or parallel tag blocks)
.
</ie:failure>
Attribute Descriptions
exception
Specifies a Java exception name for limiting the access to the failure processing code. When this attribute is included, the failure block is executed only when the exception named has occurred.
If you omit this attribute, the exception name is assumed to be “java.lang.Exception.”
Example
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The following failure tags provide general error processing for the unit and specific error processing for the IENotFoundException exception:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:unit>
<ie:failure
exception="com.infoengine.exception.fatal.IENotFoundException">
<!-- specific failure processing for IENotFoundException-->
</ie:failure>
<ie:failure>
<!--Add general failure processing here. -->
</ie:failure>
</ie:unit>
forEach
The forEach tag block allows you to iterate through an existing Info*Engine group one element at a time. The result of each iteration produces one element (including all attributes of the element) in the output group specified. This resulting element is only available within the forEach tag block for which it was produced. You can then use this output group as the input group in Info*Engine tags that are nested in the block.
Each time the forEach end tag is reached, the processing loops back to the forEach start tag until there are no more elements in the input group. After all elements have been processed, the last element in the forEach input group is now in the output group (named in the groupOut attribute). Processing continues on to the next line after the forEach end tag.
|
|
This tag cannot be nested in other Info*Engine tags, but other Info*Engine tags can be nested under this tag.
|
Syntax
<ie:forEach groupIn="group_name" groupOut="group_name">
.
. (other Info*Engine tag blocks)
.
</ie:forEach>
Attribute Descriptions
Required Attributes: groupIn and groupOut.
groupIn
Specifies the name of the Info*Engine group to use as input. For each iteration of the loop, the next element (including all attribute values in the element) from the input group is moved to the output group.
This attribute is required.
groupOut
Specifies the name of the Info*Engine group to generate for each iteration.
This attribute is required.
Example
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example assumes that the “employees” group exists as a result of a “CreateEmployeeGroup” task. The forEach tag block iterates through the “employees” group, one element at time. Nested within the block is the Display-Object webject, which displays the attributes with each element using the caption “One Employee”:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<!-- create input group -->
<ie:task uri="CreateEmployeesGroup"/>
<!-- iterate group, displaying the attributes for one employee -->
<!-- in each iteration -->
<ie:forEach groupIn="employees" groupOut="employee">
<ie:webject name="Display-Object" type="DSP">
<ie:param name="GROUP_IN" data="employee"/>
<ie:param name="CAPTION" data="One Employee"/>
</ie:webject>
</ie:forEach>
getService
The getService tag establishes a variable reference to the Info*Engine object (com.infoengine.jsp.InfoEngine) that is being used by the Info*Engine custom tags on a JSP page.
After you define the variable, you can use it in code that uses methods from the Info*Engine Server Access Kit (SAK). For example, you can access VDB information, retrieve groups, format rows and columns, and so on.
This tag also establishes implicit variable references for the context groups in use by tags within the page (com.infoengine.object.factory.Group). The variables instantiated are:
formGroup
Contains attributes that are obtained from the CGI query specification data that is received with the URL used to access the template. It also contains any HTML form data that was received as the result of a web browser POST request. This is the same information stored in the FORM context group.
serverGroup
Contains attributes that are derived from the protocol used to communicate from the web browser to the web server. It can contain values such as accept-language or auth-user. Refer to the current web-browser-to-web-server protocol specification to find more information on the individual attributes found in this group. This is the same information stored in the SERVER context group.
cookieGroup
Contains one element that has an attribute for each cookie that is processed during the connection to the JSP page. This is the same information stored in the COOKIE context group.
authGroup
Contains attributes that provide a credentials map for the task in which the webject executes. The map contains authentication information used by adapters in establishing connections to back-end information systems. Each element of a credentials map provides a username and associated credentials that are used in connecting to a specific back-end system. This is the same information stored in the Auth-Map context group.
|
|
Only use this tag on JSP pages; do not use it in standalone Info*Engine tasks.
Each page can only have one getService tag on it.
This tag cannot be embedded within other Info*Engine tags.
|
Syntax
<ie:getService varName="variable_name"/>
Attribute Descriptions
Required Attributes: varName
varName
Specifies a Java variable name for the Info*Engine object. This tag defines the variable; you do not need to define it before specifying the name here.
This attribute is required.
Example
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example creates the “EMPLOYEEdata” group through a query and then displays the number of rows in the group. To get the number of rows, the example uses the getService tag to identify the service as “ieObj” and then uses the getElementCount method from com.infoengine.object.factory.Group class to retrieve the number of rows:
getValue
The getValue tag retrieves the string value of the specified attribute from the first element in the input group.
This tag can be nested in other Info*Engine tags.
Do not imbed this tag in scriptlets; doing so causes a compiler error because the tag is read as plain text. For example, the following scriptlet does not compile:
<%
float total = 0;
%>
<ie:forEach ...>
<% total += <ie:getValue name="SAL"/>;%>
</ie:forEach>
Instead, within a scriptlet you can use the getAttributeValue method. For an example that uses this method, see the “Examples” section below.
Syntax
<ie:getValue name="attr_name" groupIn="group_name"/>
Attribute Descriptions
Required Attributes: name
groupIn
Specifies the name of the Info*Engine group to use as the input group.
This attribute is optional. If you omit this attribute, the last group added to the VDB is used.
name
Specifies the name of the attribute whose value you want to retrieve from the first element in the Info*Engine input group.
This attribute is required.
Examples
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example assumes that the “employees” group exists as a result of a “CreateEmployeesGroup” task. The getValue tags are nested within table HTML tags, producing values for elements in the table rows that are displayed.
The following example page uses the getValue tags to display selected attributes in each element and uses a scriptlet to calculate a running salary total. Computing the salary total uses the Info*Engine getAttributeValue method:
<%@page language="java" session="false" errorPage="../IEError.jsp"
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<!-- create a group that contains employee name, number, and salary -->
<ie:task uri="CreateEmployeesGroup"/>
<html>
<body>
<ie:getService varName="pie"/>
<% float tot_sal = 0; %>
<!-- iterate group, displaying the salary for one employee -->
<!-- in each iteration and calculating the total salary -->
<ie:forEach groupIn="employees" groupOut="one-element">
<b>Employee Number</b>:<ie:getValue name="EMPNO"/><br>
<b>employee name:</b><ie:getValue name="ENAME"/><br>
<b>salary:</b>$<ie:getValue name="SAL"/><br>
<hr><br>
<%
String ssal = pie.getAttributeValue ( "one-element", 0, "SAL" );
tot_sal += Float.parseFloat ( ( (ssal != null && !ssal.equals(""))
? ssal :
"0" ) );
%>
</ie:forEach>
<!-- Display the salary total for all employee in the group -->
<b>Salary Total:</b>$<%=tot_sal%><br>
</html>
</body>
init
The init tag supplies the initialization for a unit. The code between the start and end init tags executes first in a unit each time the unit is executed. Using an init code block allows you to identify specific code that always executes first when the unit is executed, even if the code block is not at the beginning of the unit. For example, in the initialization code, you could save the initial state of any objects that are manipulated in the unit. Then, if an error occurs in the body of the unit, the failure block could restore the objects to this initial state.
If a failure occurs in an init tag block, the error is returned to the code block from which the unit was executed. For example, assume that a JSP page has one unit nested in another unit as follows:
<!-- Top of page -->
:
:
<!-- First Unit -->
<ie:unit>
<ie:init>
<!-- Initialization of First Unit -->
<!-- Errors occurring here are passed back to the page -->
</ie:init>
<!-- Body of First Unit -->
<ie:webject > … </ie:webject>
<ie:webject > … </ie:webject>
<!-- Nested Unit -->
<ie:unit>
<ie:init>
<!-- Initialization of Nested Unit -->
<!-- Errors occurring here are passed back to first unit -->
</ie:init>
<!-- Body of Nested Unit -->
<ie:webject > … </ie:webject>
<ie:webject > … </ie:webject>
<ie:failure>
<!-- Nested Unit failure processing accessed when -->
<!-- there is an error in the body of the nested unit -->
</ie:failure>
<!-- End of Nested Unit -->
</ie:unit>
<ie:failure>
<!-- First Unit failure processing accessed when -->
<!-- there is an error in the body of the first unit-->
</ie:failure>
<!-- End of First Unit -->
</ie:unit>
<!-- Page Error Processing-->
:
:
<!-- End of Page-->
If the initialization of the nested unit fails, the failure is recorded as an error in the body of the first unit. If the initialization of the first unit fails, this error is processed by the page, which may automatically send it to its error page.
Scriptlets that are nested in unit, init, success, and failure tag blocks are not processed on JSP pages the same way they are processed in the Info*Engine task processor. Use the following guidelines to determine when you can nest scriptlets in these tags:
• You can nest scriptlets within tag blocks in a standalone task.
• You should not nest scriptlets in any tag block on a JSP page. Instead, create standalone tasks that contain the scriptlets. You can execute these tasks from the JSP page by using the Info*Engine task tag.
For more information, see
Scriptlets.
|
|
Embedded HTML is not supported within init tags in JSPs.
You nest this tag in unit tag blocks.
You can nest multiple webject, task, unit, and parallel tags in this tag block.
|
Syntax
<ie:init>
.
. (webject, task, unit, or parallel tag blocks)
.
</ie:init>
parallel
The parallel tag allows you to define a set of webjects or tasks that are executed concurrently.
Each webject and each task that is nested in a parallel tag block is executed in its own environment at the same time as the other webjects and tasks in the block. After all of the webjects and tasks successfully complete, then the VDBs of the individual processes are merged with the VDB in use by the page or task. Processing continues starting with the line after the parallel end tag.
If an exception occurs within the parallel block, by default the exception is propagated outside the parallel block after the parent VDB has been updated. If a webject or task within a parallel tag block fails, you should assume that the content of the resulting VDB is unpredictable.
You can nest this tag in unit, init, success, or failure tag bocks. You can also nest multiple webject and task tags in this tag block.
|
|
Display webjects cannot be nested in a parallel tag bock.
|
Syntax
<ie:parallel>
.
. (webject or task tag blocks)
.
</ie:parallel>
Example
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The following parallel tag block executes two Query-Object webjects and a task at the same time:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:parallel>
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="INSTANCE" data="jndiAdapter"/>
<ie:param name="FILTER" data="(objectClass=*)"/>
<ie:param name="GROUP_OUT" data="dirOut"/>
</ie:webject>
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="INSTANCE" data="jdbcAdapter"/>
<ie:param name="CLASS" data="EMP"/>
<ie:param name="WHERE" data="()"/>
<ie:param name="GROUP_OUT" data="dbOut"/>
</ie:webject>
<ie:task URI="stask.xml">
<ie:param name="P1" data="v1"/>
<ie:param name="P2" data="v2"/>
<ie:param name="GROUP_OUT" data="people"/>
<ie:param name="GROUP_OUT" data="employees"/>
</ie:task>
</ie:parallel>
If this parallel tag block is part of a JSP page, all four of the groups created in the block are available to any display webjects that follow the block. If the block is in a task, you would use the Return-Groups webject after the block to make the groups available to display webjects.
param
The param tag defines a parameter for use within webject tags, task tags, and directory service tags:
• Webject parameters provide the input criteria for the webject in which they are specified.
• Task parameters provide a way to set the following items:
◦ @FORM context group variables so that they are available to the task.
◦ The VDB groups that are available to the task.
◦ The VDB groups that are available when the task finishes.
• Directory service parameters provide the names of groups that are used as input to and output from creating, updating, querying, and listing directory service entries.
In each case, the parameter requirements are dictated by the individual webjects, tasks, and directory service actions where they are specified. For additional information, see the description of the specific webject, task, or directory service action you want to accomplish.
You can include expressions as attribute values on a
param tag. For more information, see
Expressions.
You can nest this tag in the webject, task, createObjects, listObjects, queryObjects, and updateObjects tags.
Syntax
<ie:param name="PARAMETER_NAME"
data="value_list"
delim="delimiter"
default="default_value"
elementSeparator="character"
valueSeparator="character"/>
Attribute Descriptions
Required attributes: name and data.
data
Specifies one or more data values to assign to the parameter named in the name attribute. Include the data values within quotation marks. The number and type of data values that you can assign are determined by the specific parameter.
For parameters that can have multiple data values assigned to them, the most common way to enter multiple data values is by including multiple param tags, all with the same name attribute and different data attributes.
You can also include multiple values in the data attribute by separating the values using a delimiter and including the separator in delim attribute. To use the comma as a value separator, use the following syntax:
data="value1,value2,…,valueN" delim=","
For example, to return multiple groups in the Return-Groups webject, you can include either the following two param tags:
<ie:param name="GROUP_IN" data="employees"/>
<ie:param name="GROUP_IN" data="consultants"/>
or one param tag that includes the delim attribute:
<ie:param name="GROUP_IN" data="employees,consultants" delim=","/>
The data attribute is required.
default
Specifies a literal string, which is the default value that is used if a substitution expression returns no values. When you specify this attribute, you must include the default value within quotation marks.
Whenever you include substitution expressions in the data attribute, you should include a default for the expression. For example, the following param tag sets the default for the ATTRIBUTE parameter to the string “*”:
<ie:param name="ATTRIBUTE" data="$(@FORM[]attr[])" default="*"/>
This attribute is optional.
delim
Defines the delimiting symbol that Info*Engine uses to separate multiple values in the data attribute. When you specify this attribute, you must include the symbol within quotation marks. For example, if you want to use the comma as the delimiter, the syntax for the data and delim attributes is:
data="value1,value2,…,valueN" delim=","
The following param tag example has three values defined in the data attribute and uses the comma as the delimiter:
<ie:param name="ATTRIBUTE" data="ename,phone,title" delim=",">
By using multiple param tags that have only one value in each data attribute, this same parameter could also have been specified as follows:
<ie:param name="ATTRIBUTE" data="ename">
<ie:param name="ATTRIBUTE" data="phone">
<ie:param name="ATTRIBUTE" data="title">
In an actual webject, the resulting parameter in both cases tells the processor that the webject expects to receive employee name (ename), employee telephone number (phone), and employee title (title) information within the group of data returned from the data repository.
This attribute is optional.
elementSeparator
Specifies the element separator that Info*Engine uses when processing substitution expressions that are in the data attribute. The specified character is used when concatenating together attribute values from multiple elements (rows). The selection of multiple elements can occur when the expression contains the asterisk (*) as the element selector.
The following param tag includes a substitution expression in the data attribute that has the asterisk as the element selector and sets the element separator to “#”:
<ie:param name="ATTRIBUTE" data="$(grp1[*]attr[0]}" elementSeparator="#"/>
This attribute is optional.
name
Specifies a parameter name to which a data value is assigned. Include the parameter name within quotation marks. The names of the parameters are not case-sensitive, but are documented using upper case characters.
This attribute is required.
valueSeparator
Specifies the value separator that Info*Engine uses when processing substitution expressions that are in the data attribute. The specified character is used when concatenating together multiple values that are contained in one attribute location. The location is defined by an attribute (column) and an element (row) pair that results from processing substitution expressions. Multiple values can occur when the expression contains the asterisk (*) as the value selector.
The following param tag includes a substitution expression in the data attribute that has the asterisk as the value selector and sets the value separator to “|”:
<ie:param name="ATTRIBUTE" data="$(grp1[0]attr[*])" valueSeparator="|"/>
This attribute is optional.
Example
The following example declares that the page or task uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The param tags define two parameters for the Copy-Group webject:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:webject name="Copy-Group" type="GRP">
<ie:param name="GROUP_IN" data="grp1"/>
<ie:param name="GROUP_OUT" data="grp2"/>
</ie:webject>
resetService
The resetService tag resets the Info*Engine object (com.infoengine.jsp.InfoEngine) that is being used by the Info*Engine custom tags on a JSP page or in a session. If you include a page scope, the reset object exists only while the page executes. If you specify a session scope, the reset object is available to all pages in the session.
When you reset an Info*Engine object using a page scope, the following things happen:
• All VDB groups that were available to the page are no longer available in the new object.
• All VDB groups created after the object is reset are only available to the page (even if the page directive for the page includes session=TRUE).
You can copy a group from a session VDB to a page VDB or from a page VDB to a session VDB using the addGroup method from the com.infoengine.object.factory.Group class.
When you reset an Info*Engine object using a session scope, all VDB groups that were available to the session are no longer available in the new object.
Unless you explicitly save an existing Info*Engine object, the existing object is no longer available when you reset the object using the resetService tag.
If you supply a new variable name for the reset object, the new service object can be referenced by the name in code that uses methods from the Info*Engine Server Access Kit (SAK). For example, you can access VDB information, retrieve groups, format rows and columns, and so on.
The resetService tag can be very useful in the following situations:
• Avoiding conflicts when accessing groups in the VDB. You may need to do this when an application that consists of multiple JSP pages has session scope and there can be multiple requests for VDB groups occurring at the same time. Ensuring that each request gets back the intended groups may not be possible unless you reset the Info*Engine object for each page. This allows you to restrict the groups available in the VDB to those created on the page while setting other information to a session scope.
• Cleaning up the VDB. When your application has created many VDB groups that are no longer needed by the application, you can reset the VDB to free up resources.
|
|
Only use this tag on JSP pages; do not use it in standalone Info*Engine tasks.
You can include multiple resetService tags on the same page as long as you either omit the variable name or specify unique object names. You cannot specify the same variable name on multiple resetService tags, or conversely on a getService tag and a resetService tag.
This tag cannot be embedded within other Info*Engine tags.
|
Syntax
<ie:resetService varName="variable_name"
scope="[PAGE | SESSION]"/>
Attribute Descriptions
varName
Specifies a Java variable name for the Info*Engine object. This tag defines the variable; do not define it before specifying the name here. The variable name cannot be the same name specified in either the getService tag or other associated resetService tags.
This attribute is optional. If omitted, the object cannot be referenced through SAK methods.
scope
Specifies where the Info*Engine object is stored. The valid values for scope are:
PAGE—Sets the object scope to the page in which the tag is used.
SESSION—Sets the object scope to the session in which the tag is used.
This attribute is optional. If omitted, the value defaults to the location of the Info*Engine object in use. If session=true on the page directive, then the session Info*Engine object is reset. Otherwise, the page Info*Engine object is reset.
Example
The following example declares that the page has a session scope and uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example expands on the getService tag example which gets the number of rows in the “EMPLOYEEdata”. The example resets the service object for the page using the resetService tag and continues on with other queries:
|
|
Because the resetService tag only resets the service for remainder of the page, at the end of the page processing, the session VDB still includes the “EMPLOYEEdata” group.
|
success
The success tag allows you to supply code for success processing within a unit. The code between the start and end success tag executes only when the body of the unit completes successfully.
If a failure occurs in this block, the exception is propagated outside the enclosing unit block.
Nest this tag in unit tag blocks. You can also nest multiple webject, task, unit, and parallel tags in this tag block.
Scriptlets that are nested in unit, init, success, and failure tag blocks are not processed on JSP pages the same way they are processed in the Info*Engine task processor. Use the following guidelines to determine when you can nest scriptlets in these tags:
• You can nest scriptlets within tag blocks in a standalone task.
• You should not nest scriptlets in any tag block on a JSP page. Instead, create standalone tasks that contain the scriptlets. You can execute these tasks from the JSP page by using the Info*Engine task tag.
For more information, see
Scriptlets.
|
|
Embedded HTML is not supported within success tags in JSPs.
|
Syntax
<ie:success>
.
. (webject, task, unit, or parallel tag blocks)
.
</ie:success>
Example
See the unit tag example below.
task
The task tag identifies an XML task that you want to execute.
You can nest this tag in unit, init, parallel, success, and failure tag blocks.
You can specify the parameters for a task by nesting the param tag within this tag block. Task parameters provide a way to set the following items:
• The VDB groups that are available to the task. Specifying GROUP_IN task parameters allows you to define which groups are initially available to the task.
• The VDB groups that are available when the task finishes. Specifying GROUP_OUT task parameters allows you to filter the groups that are returned to the VDB of the task in which the nested task is executed.
By default, the GROUP_OUT parameter on the last webject executed identifies the groups that are returned. If there is no GROUP_OUT webject parameter, then the last group added to the VDB is returned.
When multiple groups are returned through the last webject (which can be the case with the Return-Groups webject), specifying a subset of these groups in GROUP_OUT task parameter limits the groups that are returned to the VDB of the calling task.
• @FORM context group variables so that they are available to the task. An @FORM context group variable is set for each parameter name and data pair that you specify in a param tag nested in a task tag block. This includes any GROUP_IN and GROUP_OUT parameters specified for the task.
Because the @FORM group GROUP_IN variables contain the names of the VDB groups that are initially available in the task, you can get the VDB group names by reading the values from the @FORM group GROUP_IN variables.
|
|
Using this tag with the Info*Engine task processor .secret.text or .secret.text2 and .secret.algorithm properties allows for validation to occur before a remote processor executes the task. For information about configuring these properties, see the Configuring Request Validation section in Configuring Info*Engine Capabilities. |
Syntax
When there are parameters, you can use the following syntax:
<ie:task uri="uri_task_source"
processor="processor1"
processor="processor2"
.
.
.
processor="processorn"
resumable="[true|false]">
.
. (Nest task parameters using param tags)
.
</ie:task>
When there are no parameters, you can use the following syntax:
<ie:task uri="uri_task_source"
processor="processor1"
processor="processor2"
.
.
.
processor="processorn"
resumable="[true|false]"/>
Attribute Descriptions
Required attribute: uri
processor
Specifies one or more names of remote Info*Engine task processors to which the task can be sent for execution. Each name you specify must map to a task processor that is available from your current environment. The names you can specify in this attribute are those service names defined for task processors through the Info*Engine Property Administration utility.
This attribute is optional. When it is not specified, the task named in the task tag is executed by the task processor that is currently executing the JSP page or task that contains the task tag. For JSP pages, the task processor used by default is running in the JSP engine. To direct the nested task to execute in the Info*Engine Server task processor (rather than in the JSP engine), you must include the processor attribute that identifies the server task processor. For example, if the task processor has the default name of “com.myCompany.server.taskProcessor” you can include the following processor attribute:
processor="com.myCompany.server.taskProcessor"
If your current environment has other task processors set up for your use, you can direct the task to choose one of those task processors by specifying the processor names on processor attributes in the order you want them selected. For example, assume that your site has set up “xxx.taskProcessor” and “yyy.taskProcesor” for your use, and that you would prefer running the task on “yyy.taskProcessor”. To accomplish this, include the following processor attributes in the task tag:
<ie:task uri="task1.xml" processor="yyy.taskProcessor" processor=
"xxx.taskProcessor" processor="zzz.taskProcessor" />
Notice that the third processor named is the “zzz.taskProcessor.” It is only used if both of the other processors are not available.
resumable
Indicates whether the VDB state must be saved before running the subtask named in this task tag. This attribute is only used when guaranteed task execution has been enabled and the task tag is executed from a task.
If you omit the attribute (or set it to false) and guaranteed task execution is enabled, then Info*Engine saves the state of the VDB before running the task. When this is done, the VDB can be restored in the case where the task must be rerun.
If you set the attribute to “true” and guaranteed task execution is enabled, then Info*Engine does not save the state of the VDB before running the task. Set resumable to true when the task can be run without causing side effects that would prevent the task from producing the same results if it were run again.
uri
Specifies a URI that is the location of the XML task file to execute. The URI can be a relative or absolute URI:
◦ Relative URIs reference files that reside under the root file system directory that is defined for the local Info*Engine task processor.
◦ Absolute URIs reference files that reside in the local file system, reside on a remote HTTP server, or are referenced through an accessible LDAP directory.
This attribute is required.
Example
The following example declares that the page or task uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example task tag executes the task1.xml file that is in the root file directory defined for the local task processor. The nested parameter sets the FORM variable attr to “ENAME”:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:task uri="task1.xml">
<ie:param name="attr" data="ENAME"/>
</ie:task>
unit
The unit tag allows you to group a sequence of webjects, tasks, or Java code so that the group is executed as a unit. Within the unit, you can supply the main body and can also define the following nested tags to explicitly code special parts of the unit:
• The init tag block supplies the initialization for the unit. The code between the start and end init tag executes first in the unit.
• The success tag block provides a way to specify code that executes only when the code in the body of the unit has completed successfully.
• The failure tag block provides a way to specify code that executes only when the code in the body of the unit has failed. You can include multiple failure tag blocks in which you can specify error processing for specific errors.
The main body of a unit consists of all webjects, tasks, and Java code within the unit start and end tags, but outside of the nested init, success, and failure tag blocks.
The placement of the init, success, and failure tag blocks in the unit have no significance. When the unit executes, the code in the init tag block executes first regardless of where it is in the unit. If it completes successfully, then the code in the body of the unit executes in the order it is presented in the code, starting at the beginning of the unit. If the body completes successfully, then the code in the success tag block executes. If any code in the body fails, then the failure tags in the unit are checked to determine if processing for that error has been provided. If you provide error processing for the error that has occurred, then that code executes.
If an exception occurs in a success block, the exception is thrown and the unit is not processed. If an exception occurs in the body of the unit, then it is processed by a failure tag (if one is defined for the exception) or by a general failure tag. If an error in the body of a unit is not caught through a failure tag, the error is not handled.
You can nest this tag in other unit tag blocks and in init, success, and failure tag blocks.
You can nest one init tag block, one success tag block, and one or more failure tag blocks in this tag block. You can also nest multiple webject, task, unit, and parallel tags in this tag block.
For additional information about the init, success, and failure tags, see the section that corresponds to each tag.
Scriptlets that are nested in unit, init, success, and failure tag blocks are not processed on JSP pages the same way they are processed in the Info*Engine task processor. Use the following guidelines to determine when you can nest scriptlets in these tags:
• You can nest scriptlets within tag blocks in a standalone task.
• You should not nest scriptlets in any tag block on a JSP page. Instead, create standalone tasks that contain the scriptlets. You can execute these tasks from the JSP page by using the Info*Engine task tag.
For additional information about scriptlets, see
Scriptlets.
|
|
Embedded HTML is not supported within unit tags in JSPs.
|
Syntax
<ie:unit>
.
. (webject, task, init, unit, parallel, success, and failure tag blocks.)
.
</ie:unit>
Example
The following example declares that the page uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example unit tag groups the main body containing the Query-Objects webject with a success and failure block. The Query-Objects webject executes and, if it completes successfully, then the success block executes. If it does not complete successfully, then the failure block executes:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:unit>
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="INSTANCE" data="adapter"/>
<ie:param name="CLASS" data="salesemp"/>
<ie:param name="WHERE" data="()"/>
<ie:param name="GROUP_OUT" data="sales">
</ie:webject>
<ie:success>
<ie:webject name="Display-Table" type="DSP">
<ie:param name="GROUP_IN" data="sales"/>
<ie:param name="ATTRIBUTE" data="ename,phone,title" DELIM=","/>
<ie:param name="HEADER" data="Name,Telephone,Title" DELIM=","/>
</ie:webject>
</ie:success>
<ie:failure>
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="FAILURE=query failed"/>
<ie:param name="GROUP_OUT" data="failure"/>
</ie:webject>
<ie:webject name="Display-Table" type="DSP">
<ie:param name="GROUP_IN" data="failure"/>
<ie:param name="ATTRIBUTE" data="FAILURE"/>
</ie:webject>
</ie:failure>
</ie:unit>
webject
The webject tag identifies the webject you want to execute.
On JSP pages, you can name any defined webject in the webject tag.
You can nest this tag in unit, init, success, failure, and parallel tag blocks.
For webjects that require parameters, you specify the parameters by nesting the param tag in this tag block.
|
|
In standalone tasks, display webjects are not allowed.
Display webjects are not allowed to be embedded within parallel tag blocks.
|
Syntax
When there are parameters, you can use the following syntax:
<ie:webject name="Webject-Name"
type="TYPE_CONSTANT"
resumable="[true|false]"
use="webject_class_path">
.
. (Nest webject parameters using param tags)
.
</ie:webject>
When there are no parameters, you can use the following syntax:
<ie:webject name="Webject-Name"
type="TYPE_CONSTANT"
resumable="[true|false]"
use="webject_class_path"/>
Attribute Descriptions
Required attributes: name and type
name
Specifies an Info*Engine webject name. This attribute is required.
resumable
Indicates whether the VDB state must be saved before running the webject named in this webject tag. This attribute is only used when guaranteed task execution has been enabled and the webject is an action webject (TYPE=ACT) that resides in a task.
If you omit the attribute (or set it to false) and guaranteed task execution is enabled, then Info*Engine saves the state of the VDB before running the action webject. When this is done, the VDB can be restored in the case where the webject must be rerun.
If you set the attribute to true and guaranteed task execution is enabled, then Info*Engine does not save the state of the VDB before running the webject in a task. Set resumable to true when the webject can be run without causing side effects that would prevent the webject from producing the same results if it were run again.
type
Indicates the type of webject you want to use. The type determines which package is searched for the webject class file. Info*Engine type constants are defined for the following types of webjects:
|
Type Constant
|
Webject Type
|
|
DSP
|
Display
|
|
IMG
|
Image
|
|
ACT
|
Action
|
|
OBJ
|
Query
|
|
GRP
|
Group
|
|
EXT
|
External
|
|
MGT
|
Management
|
|
MSG
|
Messaging
|
|
WES
|
Web Event Service
|
This attribute is required.
|
|
Display webjects (type=DSP) cannot be used in Info*Engine tasks.
|
The Messaging (type=MSG) and Web Event Service (type=WES) webjects were developed for use in Info*Engine tasks. These types of webjects should not be used directly within a JSP page, although no exception is thrown. The webjects should be called from a JSP page using the task tag with a processor attribute.
use
Specifies the path to the class containing the external webject when the webject named is not a class within.
This attribute is required when the type attribute is set to EXT.
Example
The following example declares that the page or task uses tags from the Info*Engine core tag library and that the tags have the ie prefix. The example webject tag names the Copy-Group webject, which is a group webject that has two parameters:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:webject name="Copy-Group" type="GRP">
<ie:param name="GROUP_IN" data="grp1"/>
<ie:param name="GROUP_OUT" data="grp2"/>
</ie:webject>
