Clipping Programmer's Guide
379
}
public List selectAvailableRQLEngines() {
updateAvailableEngines();
return _availableEngines;
}
public void updateAvailableEngines() {
_availableEngines.clear();
for (Iterator<RQLEngine> eng = _engines.iterator();
eng.hasNext();) {
RQLEngine engine = eng.next();
try {
engine.request(_PING_REQUEST, _PING_HANDLER);
_availableEngines.add(engine);
} catch (RQLException e) {
// do nothing
}
}
}
}
Table 129. A Simple RQLHandler for Handling the Result of Ping
package com.mycompany.myproject;
import com.kapowtech.robosuite.api.java.rql.RQLException;
import com.kapowtech.robosuite.api.java.rql.construct.RQLResponse;
import com.kapowtech.robosuite.api.java.rql.engine.RQLHandler;
public class myPingRQLHandler implements RQLHandler {
public void handleError(RQLException e) throws RQLException {
throw e;
}
public void handleFatal(RQLException e) throws RQLException {
throw e;
}
public void handleResponse(RQLResponse response)
throws RQLException {
// do nothing
}
}
In 
the 
implementations 
of 
RoundRobinDistributionPolicy 
and
RandomDistributionPolicy, the knowledge of availability is put in the hands of the RQLEngine
itself (an engine wrapping another engine as described in the Java Programmer’s Guide). This means that
you do not have to ping the server to know whether it is available, but can do it at each request to the
RQLEngine. It is then the responsibility of the Distribution Policy to return the engines to service. This is
done by pinging each unavailable engine after a certain interval — if the engine is still not available this is
repeated after increasingly longer intervals. While the implementation given above is significantly simpler
than this, it is hoped that it illustrates the principles, so you will be able to write your own Distribution
Policy.
Pdf link to specific page - insert, remove PDF links in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Free C# example code is offered for users to edit PDF document hyperlink (url), like inserting and deleting
adding hyperlinks to pdf documents; add hyperlink to pdf
Pdf link to specific page - VB.NET PDF url edit library: insert, remove PDF links in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Help to Insert a Hyperlink to Specified PDF Document Page
adding an email link to a pdf; add links to pdf
Clipping Programmer's Guide
380
Handlers
This section describes the handler extension points in the clipping servlet. Handlers are called when
execution of the clipping robot has terminated on the RoboServer — either successfully or by returning an
error. Handlers can intercept the returned values (an Additional Output Objects handler) or the exception
thrown in case of error (an error handler).
Additional Output Objects Handler
Additional Output Objects handlers are called by the clipping logic if the robot returns additional output
objects.
Purpose and Use
An Additional Output Objects handler gives access to values returned from the Robot. These values come
from variables in the robot returned in return steps. The returned values can be used for a variety of purposes
like being written to log files or databases, but most often they will be put in a session attribute to be read by
other servlets or portlets. The data could be a key such that other portlets can retrieve the information and
show relevant information. E.g. if you are clipping a list of invoices due for a given customer, you might
want to return the customer number, so other portlets can show other information — perhaps clipped from
other systems — concerning the same customer. Or it could be information that you navigated past in the
clipping robot — in the invoices due example, you might have navigated past a page with the customer's
address, which could be shown in another portlet.
One thing that one has to be aware of with respect to clipping portlets returning additional output objects
is that there is no way for the portlet to alert other portlets (clipping or non clipping) that the portlet has
returned an object and that these other portlets might want to update their view to reflect the change. The
reason for this is that a clip in a clipping portlet is actually an IFrame that communicates directly with a
servlet without the portlet “knowing” about this. So the clipping portlet cannot decide to refresh the portal
to let other portlets refresh their views. So if one wants to write a portlet that adjusts its view based on
objects returned by a clip portlet then one has to put in some kind of regular updating mechanism into the
portlet, such that this will update itself regularly, e.g. by using JavaScript and possibly AJAX.
Clip Configuration File Specification
To add an Additional Output Objects handler, you need to specify a class name within an additional-
output-objects tag. The following example shows how this can be done.
Table 130. Example of a Clip Configuration File with an Additional Output Objects
Handler
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE clip PUBLIC "-//Kapow Technologies//DTD Clip Deployment Descriptor 1.3//EN" "http://www.kapowtech.com/robosuite/rql/dtd/clip-deployment-descriptor_1_3.dtd">
<clip>
<robot-url>library:/my.robot</robot-url>
<robot-library><default/></robot-library>
<robot-server>
<socket-object-protocol host="localhost" port="50000"/>
</robot-server>
<additional-input-objects>
<class-name>com.mycompany.MyInputProvide</class-name>
</additional-input-objects>
<additional-output-objects>
C# PDF File & Page Process Library SDK for C#.net, ASP.NET, MVC
Image: Copy, Paste, Cut Image in Page. Link: Edit URL. XDoc.PDF allows you to easily move PDF document pages specific APIs to copy and get a specific page of PDF
adding links to pdf in preview; add links to pdf online
VB.NET PDF File & Page Process Library SDK for vb.net, ASP.NET
By referring to this VB.NET guide, you can use specific APIs to copy and get a specific page of PDF file; you are also able to copy and paste pages from a PDF
add hyperlinks to pdf online; add url to pdf
Clipping Programmer's Guide
381
<class-name>
com.mycompany.MyAdditionalOutputObjectHandler
</class-name>
</additional-output-objects>
</clip>
As described, the order of the elements in the clip descriptor must follow the order defined in the DTD
(References). The following diagram shows the location of the additional-output-objects
element in the order of these (not all elements may be present):
robot-url,  robot-library,  robot-server,  robot-server-credentials,
portlet, popups-required,  popups-blocked-text, action-header-filter,
portal-cookie-filter, user-credentials, properties, additional-input-
objects, additional-output-objects,  user-messages,  restart-session-
controller, error-handler, wait-page-text, wait-page-style
Implementation
An Additional Output Objects handler is a Java class that must implement the following interface:
com.kapowtech.robosuite.client.clip.version1.api.
AdditionalOutputObjectsHandler
This interface has one method:
void handle(HttpServletRequest request, 
HttpServletResponse response, 
RQLObjects outputObjects);
RQLObjects are mentioned in Additional Input Objects Provider and further described in the Java
Programmer's Guide. It is generated from all values returned explicitly in the clipping robot. In each object
you can then access the attribute values.
Example
The  example  below  shows  an  Additional  Output  Objects  handler  that  takes  an  attribute  value
from  an  output  object  and  places  this  in  a  session  attribute.  The  output  object  is  called
MyAdditionalOutputObject and this has one attribute url.
Table 131. Code Example of an Additional Output Objects Handler
package com.mycompany.myproject;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.kapowtech.robosuite.api.java.rql.construct.RQLObject;
import com.kapowtech.robosuite.api.java.rql.construct.RQLObjects;
import com.kapowtech.robosuite.client.clip.version1.api.
AdditionalOutputObjectsHandler;
public class MyAdditionalOutputObjectsHandler
implements AdditionalOutputObjectsHandler {
public void handle(HttpServletRequest request,
HttpServletResponse response,
VB.NET PDF Page Insert Library: insert pages into PDF file in vb.
Add and Insert Blank Page to PDF File Using VB. This demo explains how to use VB to insert an empty page to a specific location of current PDF file .
clickable links in pdf from word; add url link to pdf
C# PDF Page Insert Library: insert pages into PDF file in C#.net
Add and Insert Blank Page to PDF File in C#.NET. This C# demo explains how to insert an empty page to a specific location of current PDF file.
add link to pdf file; add a link to a pdf in acrobat
Clipping Programmer's Guide
382
RQLObjects objects) {
RQLObject rqlObject
= (RQLObject) objects.getByName("MyAdditionalOutputObject").get(0);
String url = (String) rqlObject.getAttribute("url").getValue();
request.getSession().setAttribute("com.mycompany.url", url);
}
}
The robot is a simple clipping robot that besides returning the normal ClipResponse variable also
returns additional output containing the URL of the clipped document, as shown below.
Clipping Robot Returning Additional Output
The session attribute written by the Additional Output Objects handler may be read by other portlets using
the following code:
request.getPortletSession().
getAttribute("com.mycompany.url", 
PortletSession.APPLICATION_SCOPE)
or in a JSP page by using the following code:
<%= request.getSession().getAttribute("com.mycompany.url") %>
Error Handler
Error handlers make it possible to intercept errors and deal with them in a suitable manner.
Purpose and Use
An error handler defines a strategy for handling errors in a clip. The custom error handler is only invoked
after all other handlers have failed and the clipping logic is about to throw a ServletException
causing the current request to fail. The custom error handler can forward to a portlet-specific error page
or provide localized error messages, but should not otherwise attempt to recover from the error.
Note that most portal systems (among them BEA WebLogic Portal 8.1 to 10.0) allow the user to specify
a portlet specific error page to handle exceptions, so implementing this class might not be necessary.
Clip Configuration File Specification
The example below shows how to add a reference to an error handler in a clip configuration file.
Table 132. An Example of a Clip Configuration File with an Error Handler
<?xml version="1.0" encoding="UTF-8"?>
VB.NET PDF - Annotate PDF Online with VB.NET HTML5 PDF Viewer
Click to add a text box to specific location on PDF page. Outline width, outline color, fill color and transparency are all can be altered in properties.
add page number to pdf hyperlink; add links to pdf acrobat
C# HTML5 PDF Viewer SDK to annotate PDF document online in C#.NET
Click to add a text box to specific location on PDF page. Outline width, outline color, fill color and transparency are all can be altered in properties.
pdf link to attached file; convert a word document to pdf with hyperlinks
Clipping Programmer's Guide
383
<!DOCTYPE clip PUBLIC "-//Kapow Technologies//DTD Clip Deployment Descriptor 1.3//EN" "http://www.kapowtech.com/robosuite/rql/dtd/clip-deployment-descriptor_1_3.dtd">
<clip>
<robot-url>library:/my.robot</robot-url>
<robot-library><default/></robot-library>
<robot-server>
<socket-object-protocol host="localhost" port="50000"/>
</robot-server>
<additional-output-objects>
<class-name>
com.mycompany.MyAdditionalOutputObjectHandler
</class-name>
</additional-output-objects>
<error-handler>
<class-name>com.mycompany.MyErrorHandler</class-name>
</error-handler>
</clip>
As described, the order of the elements in the clip descriptor must follow the order defined in the DTD
(References). The following diagram shows the location of the error-handler element in the order
of these (not all elements may be present):
robot-url,  robot-library,  robot-server,  robot-server-credentials,
portlet, popups-required,  popups-blocked-text, action-header-filter,
portal-cookie-filter, user-credentials, properties, additional-input-
objects,  additional-output-objects,  user-messages,  restart-session-
controller, error-handler, wait-page-text, wait-page-style
Implementation
A custom error handler must implement the following interface:
com.kapowtech.robosuite.client.clip.version1.api.
ErrorHandler
This interface has one method:
void handleError(HttpServletRequest request, 
HttpServletResponse response, 
Exception e) throws Exception;
The exception (e) in this method signature may be used to find the cause of the error to be able to produce
an appropriate error message.
Example
An example of an error handler class is given below. It will forward the request to a JSP page that will
present an error message. The handler will place the message in a request attribute such that the JSP page
can get access to this. Further below there is a simple example of how such a JSP page can be constructed.
One might decide not to handle the exception in an error handler and re-throw the exception such that the
portal or web application's default method for handling error may be invoked.
Table 133. Code Example of an Error Handler
package com.mycompany.myproject;
C# PDF remove image library: remove, delete images from PDF in C#.
Image: Copy, Paste, Cut Image in Page. Link: Edit URL. Bookmark: Edit Bookmark. Metadata: Edit Delete and remove all image objects contained in a specific PDF page
adding links to pdf; pdf links
C# PDF Image Extract Library: Select, copy, paste PDF images in C#
C#: Select All Images from One PDF Page. C# programming sample for extracting all images from a specific PDF page. // Open a document.
pdf hyperlink; chrome pdf from link
Clipping Programmer's Guide
384
import javax.servlet.RequestDispatcher;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.kapowtech.robosuite.client.clip.version1.ClipException;
import com.kapowtech.robosuite.client.clip.version1.api.ErrorHandler;
public class MyErrorHandler implements ErrorHandler {
private static final String _ERROR_JSP = "error.jsp";
public void handleError(HttpServletRequest request,
HttpServletResponse response,
Exception clipException)
throws Exception {
request.setAttribute("com.mycompany.error",
clipException.getMessage());
RequestDispatcher dispatcher
= request.getRequestDispatcher(_ERROR_JSP);
try {
dispatcher.forward(request, response);
} catch (Exception e1) {
throw new ClipException(
"ErrorHandler failed to redirect to jsp: " +
_ERROR_JSP, e1);
}
}
}
The JSP error page  error.jsp could  then look  something like  what is shown below. The page
error.jsp must be located in the same folder as the clip configuration file for the example to work.
Table 134. JSP Error Page Example
<head>
<title>Error</title>
</head>
<body>
<p>
An error has occurred: <%= request.getAttribute("com.mycompany.error") %>
</p>
</body>
Filters
Filters intercept the communication between the client and RoboServer. They are able to modify the
content of the communication: Both requests sent to RoboServer and responses from RoboServer can be
modified.
Header Filter
With a header filter, you can exclude, rewrite or even add to the list of HTTP headers sent to RoboServer
and returned from RoboServer.
Clipping Programmer's Guide
385
Purpose and Use
Some single sign on solutions (SSO) work by adding a token to the HTTP header of all calls. Suppose
that you are clipping from one internal site using this SSO solution and want to insert the clip into a portal
using the same SSO solution. Now, the SSO will append the special header to the request from the user’s
browser to the servlet and you need to make sure that the header is forwarded to RoboServer and on to
the site from which you are clipping. On the other hand, the header should not be forwarded to other sites
which are not under the SSO solution.
The SSO problem is one of the key examples of using a header filter, and the hope is that it serves to
illustrate the purpose of the filter. On the other hand, a word of caution is needed: altering or adding
headers or even just allowing headers from the user’s browser to be forwarded to RoboServer might result
in unexpected behavior. E.g. consider the situation where the user-agent is allowed to filter through:
Then the clipped site will begin to function according to the end-user's browser and not according to the
browser emulated by RoboServer (where most of the site is processed).
For this reason the default filter will exclude all headers.
Clip Configuration File Specification
If nothing is specified in the clip configuration file, no headers will be passed on. If you instead want
to allow all unrecognized extension headers to pass, you should specify the preconfigured extension-
headers filter. The following example shows how to do this.
Table 135. Header Filter Element
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE clip PUBLIC "-//Kapow Technologies//DTD Clip Deployment Descriptor 1.3//EN" "http://www.kapowtech.com/robosuite/rql/dtd/clip-deployment-descriptor_1_3.dtd">
<clip>
<robot-url>library:/my.robot</robot-url>
<robot-library><default/></robot-library>
<robot-server>
<socket-object-protocol host="localhost" port="50000"/>
</robot-server>
<user-credentials>
<class-name>com.mycompany.MyCredentialsProvider</class-name>
</user-credentials>
<action-header-filter>
<extension-headers/>
</action-header-filter>
</clip>
The  extension-headers  filter  passes  on  all  unrecognized  extension  headers.  A  header  is  an
unrecognized extension header if it is not a general, request, response, or entity header as defined in RFC
2616 (HTTP/1.1), and is not a cookie-related header (as defined in RFC 2109 and RFC 2965). This filter
will be useful in the SSO example presented above.
If you wish to write your own header filter, you specify the class name of your implementation as follows:
<action-header-filter>
<class-name>
com.mycompany.MyHeaderFilter
</class-name>
</action-header-filter>
Clipping Programmer's Guide
386
As described, the order of the elements in the clip descriptor must follow the order defined in the DTD
(References). The following diagram shows the location of the action-header-filter element in
the order of these (not all elements may be present):
robot-url,  robot-library,  robot-server,  robot-server-credentials,
portlet, popups-required,  popups-blocked-text, action-header-filter,
portal-cookie-filter, user-credentials, properties, additional-input-
objects,  additional-output-objects,  user-messages,  restart-session-
controller, error-handler, wait-page-text, wait-page-style
Implementation
If you wish to write your own header filter, your must implement the interface
com.kapowtech.robosuite.client.clip.version1.api.
HeaderFilter
This interface has one method:
public List filterHeaders(List headers)
Both the argument and the result of this method is a list of headers:
com.kapowtech.robosuite.client.clip.version1.api.
Header
A header cannot be modified, but new headers are easily constructed.
As described, the order of the elements in the clip descriptor must follow the order defined in the DTD
(References). The following diagram shows the location of the action-header-filter element in
the order of these (not all elements may be present):
robot-url,  robot-library,  robot-server,  robot-server-credentials,
portlet, popups-required,  popups-blocked-text, action-header-filter,
portal-cookie-filter, user-credentials, properties, additional-input-
objects,  additional-output-objects,  user-messages,  restart-session-
controller, error-handler, wait-page-text, wait-page-style
Example
The example below gives the implementation of a header filter, which corresponds to the default blocking
filter which excludes all headers.
Table 136. Code Example of a Header Filter
package com.mycompany.myproject;
import java.util.Collections;
import java.util.List;
import com.kapowtech.robosuite.client.clip.version1.api.
HeaderFilter;
public class MyHeaderFilter implements HeaderFilter {
public List filterHeaders(List headers) {
return Collections.EMPTY_LIST;
Clipping Programmer's Guide
387
}
}
Controllers
A controller is an extension point which allows the programmer direct control over the execution of the
robot on the server. Only one controller is available, namely the Restart Session controller, which allows
the programmer to restart the robot session.
Restart Session Controller
A Restart Session controller determines whether to restart the clipping session for a robot on a RoboServer.
Purpose and Use
It is often useful to restart the session if some of the input values to a robot have changed. An example
could be a clip that uses credentials to login to the remote site. If a user changes the credentials, the robot
should logout and login again. This would happen if the robot is told to restart its clipping session, because
this would make the robot run its logout branch (if it has one) and then run its login branch again with
the new credentials.
Clip Configuration File Specification
The following example of a clip configuration file shows how to refer to an error handler.
Table 137. Example of a Clip Configuration File with a Restart Session Controller
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE clip PUBLIC "-//Kapow Technologies//DTD Clip Deployment Descriptor 1.3//EN" "http://www.kapowtech.com/robosuite/rql/dtd/clip-deployment-descriptor_1_3.dtd">
<clip>
<robot-url>library:/my.robot</robot-url>
<robot-library><default/></robot-library>
<socket-object-protocol host="localhost" port="50000"/>
</robot-server>
<restart-session-controller>
<class-name>
com.mycompany.MyRestartSessionController
</class-name>
</restart-session-controller>
<error-handler>
<class-name>com.mycompany.MyErrorHandler</class-name>
</error-handler>                    
</clip>
As described, the order of the elements in the clip descriptor must follow the order defined in the DTD
(References). The following diagram shows the location of the restart-session-controller
element in the order of these (not all elements may be present):
robot-url,  robot-library,  robot-server,  robot-server-credentials,
portlet, popups-required,  popups-blocked-text, action-header-filter,
portal-cookie-filter, user-credentials, properties, additional-input-
objects,  additional-output-objects,  user-messages, restart-session-
controller, error-handler, wait-page-text, wait-page-style
Clipping Programmer's Guide
388
Implementation
A Restart Session controller must implement the interface:
com.kapowtech.robosuite.client.clip.version1.api.
RestartSessionController
This interface has one method:
public boolean shouldRestartSession(HttpServletRequest request, 
HttpServletResponse response)
The method should return true when the robot session should be restarted.
Example
In this section, we just give a fragment of an example of the use: We leave unspecified how to decide
when to restart. In Communication between Portlet and Servlet, we will see how we can communicate this
information from the surrounding portlet to the servlet and hence on to the controller. The next section will
also illustrate how to extend the portlet, and these two techniques in combination will allow us to extend
the portlet with an edit page where the end-user can control the restart.
A prototype of a Restart Session controller is shown below.
Table 138. Example of a Restart Session Controller
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.kapowtech.robosuite.client.clip.version1.api.RestartSessionController;
public class MyRestartSessionController
implements RestartSessionController {
public boolean shouldRestartSession(HttpServletRequest request,
HttpServletResponse response)
{
final Boolean shouldRestart = ...
return shouldRestart;
}
}
Tips and Tricks
This section discusses some common use cases and present ideas of how to solve them.
Extending the Standard Portlet
You can extend the functionality of your clipping portlet by extending the ClipJavaPortlet class,
which by default is used for all clipping portlets. Remember to change the <portlet-class> in
portlet.xml to point to your implementation. E.g.:
<portlet-class>
clippingapi.ClipJavaPortletWithHelp
Documents you may be interested
Documents you may be interested