addEventCallback

void session.addEventCallback ( EventFireTime eventTime, EventHandler callback ) (professional and enterprise editions only)
void session.addEventCallbackWithPriority ( EventFireTime eventTime, EventHandler callback, int priority ) (professional and enterprise editions only)

Description

Add a runnable that will be executed at the given time.

Note: session.addEventCallback is automatically executed at a priority of 0.

Parameters

  • eventTime The time to execute a callback.
  • callback The callback to execute.
  • priority The prority for this callback. Lower numbers are higher priority.

Return Values

Returns void.

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

Sets a handler to do something after the scripts set to run at the end of the session have run.

   // using the default callback with the priority being 0.
   session.addEventCallback(SessionEventFireTime.AfterEndScripts, handler);
   
   // if we need to set the priority to be something else (or variable) use the second option
   // in this case the priority could still be set to 0 if you wanted to.
   session.addEventCallbackWithPriority(SessionEventFireTime.AfterEndScripts, handler, 3);

More Examples

EventFireTime

The EventFireTime is an interface which defines the methods that a fire time must have and so the addEventCallback method can take different types of fire times.

A number of different types of classes based on this interface have been defined for you which call out the various parts of a scrape that you can add event handlers to. Those are defined below.

ExtractorPatternEventFireTime

ExtractorPatternEventFireTime

Enum

  • BeforeExtractorPattern Before an extractor is applied (including before any scripts on it run). The returned value should be a boolean and indicates whether the extractor should be run or not. Any non-boolean result is the same as true. Also note that regardless of whether the extractor will be run or not, the event for after extractor pattern will still be fired.
  • AfterExtractorPatternAppliedButBeforeScripts After an extractor is applied (but before any scripts on it run &emdash; including the after apparent match scripts).
  • AfterEachExtractorMatch After each match of an extractor. This will be applied before any of the "After each pattern match" scripts are applied.
  • AfterExtractorPattern After an extractor is applied (including any scripts on it run).

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

How to use the EventFireTime with the session.addEventcallback method.

    session.addEventCallback(ExtractorPatternEventFireTime.AfterEachExtractorMatch, handler);

ScrapeableFileEventFireTime

ScrapeableFileEventFireTime

Enum

  • BeforeScrapeableFile Before a scrapeable file is launched (inlcuding before any scripts on it run).
  • BeforeHttpRequest Fired right before the http request (after any "before scrapeable fie" scripts, and wil fire each time the request is retired). If it returns a non-null String, that will be used as the response instead of issuing a request. This response will still get passed into the AfterHttpRequest even, but it will not pass through any tidying.
  • AfterHttpRequest Fire right after the http response and running tidy, if set, but before anything else happens. Returns the data that should be used as the response data.
  • AfterScrapeableFile After a scrapeable file is completed (including afer any scripts on it run).
  • OnHttpRedirect* Called when a redirect will occur, and returns true if a redirect should occur or false if it should not (any non boolean results in no chanage).

*Note: When using the Async HTTP client you will have access to the request builder from ScrapeableFileEventData.getRedirectRequestBuilder() which can be used to modify and adjust the request before it is sent. If you use the Apache HTTP client the getRedirectRequestBuilder() method will always return null.

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

How to use the EventFireTime with the session.addEventcallback method.

    session.addEventCallback(ScrapeableFileEventFireTime.BeforeScrapeableFile, handler);

getRedirectToURL

String scrapeableFileEventData.getRedirectToURL ( )

Description

Returns the RedirectToURL value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the RedirectToURL value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the redirect URL

    public Object handleEvent(EventFireTime fireTime, ScrapeableFileEventData data) {
        String url = data.getRedirectToURL();
       
        // do something
    }

ScriptEventFireTime

ScriptEventFireTime

Enum

  • AfterScript After a script is executed
  • BeforeScript Before a script is executed
  • OnScriptEnd Run when the script finishes executing. The difference between AfterScript and this is that AfterScript fires after the script is done running, and this runs after all the developer code has run but the script engine is still active. The return value is an injected string to execute, or null (or the empty string) to do nothing aside from execute the script code.
  • OnScriptError Executes when an error occurs in a script.
  • OnScriptStart Run when the script beings to execute. The difference between BeforeScript and this is that BeforeScript fires as preparation is made to launch a script, and this runs after all the default pre-script code is executed by the script engine, but before the developer code in the script. The return value is an injected string to execute, or null (or the empty string) to do nothing aside from execute the script code.

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

How to use the EventFireTime with the session.addEventcallback method.

    session.addEventCallback(ScriptEventFireTime.OnScriptEnd, handler);

SessionEventFireTime

SessionEventFireTime

Enum

  • AfterEndScripts After the scrape finishes and all
  • NumRecordsSavedModified When the ScrapingSession.addToNumRecordsScraped(Object) is called, this will also be called. The returned value will be the actual value to add.
  • StopScrapingCalled When the session is stopped, either by calling the stopScraping method or clicking the stop scraping button in the workbench.
  • SessionVariableSet* Called whenever a session variable is set. This is called before the value is actually set. The variable value passed in will be the new value to be set, and the return value of the handler will be the actual value returned.
  • SessionVariableRetrieved* Called whenever a session variable is retrieved. This is called after the value is retrieved. The variable value passed in will be the current value, and the return value of the handler will be the actual value returned.

*Note: Calling a setVariable or getVariable method in here WILL trigger the events for those again. Avoid infinite recursion please!

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

How to use the EventFireTime with the session.addEventcallback method.

    session.addEventCallback(SessionEventFireTime.AfterEndScripts, handler);

StringOperationEventFireTime

StringOperationEventFireTime

Enum

  • HttpParameterEncodeKey Called when an http parameter key (GET or POST) is encoded. The input string will be the value that is already encoded, and the return value should be the value to actually use.
  • HttpParameterEncodeValue Called when an http parameter value (GET or POST) is encoded. The input string will be the value that is already encoded, and the return value should be the value to actually use.

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

How to use the EventFireTime with the session.addEventcallback method.

    session.addEventCallback(StringOperationEventFireTime.HttpParameterEncodeKey, handler);

EventHandler

EventHandler EventHandler ( ) (professional and enterprise editions only)

Description

Creates an EventHandler callback object which will be called when the event triggers

Change Log

Version Description
6.0.55a Introduced for pro and enterprise editions.

Examples

Define a handler for the session.addEventCallback to use.

    // Create an EventHandler object which will be called when the event triggers
    EventHandler handler = new EventHandler()
    {
        /**
        * Returns the name of the handler.  This method doens't need to be implemented
        * but helps with debugging (on error executing the callback it will output this)
        */
        public String getHandlerName()
        {
            return "A test event handler";
        }

        /**
        * Processes the event, and potentially returns a useful value modifying something
        * in the internal code
        *
        * @param fireTime The fire time of the event. This helps when using the same handler
        * for multiple event times, to determine which was called
        * @param data The actual data from the event. Based on the event time this
        * will be a different type. It could be SessionEventData, ScrapeableFileEventData,
        * ScriptEventData, StringEventData, etc...  It will match the fire time class name
        *
        * @return A value indicating how to proceed (or sometimes the value is ignored)
        */
        public Object handleEvent(EventFireTime fireTime, AbstractEventData data)
        {
            // While you can specifically grab any data from the data object,
            // if this is a method that has a return value that matters,
            // it's best to get it as the last return value, so that multiple
            // events can be chained together.  The input data object
            // will always have the original values for all the other getters
            Object returnValue = data.getLastReturnValue();

            // Do stuff...

            // The EventFireTime values describe in the documentation what the return
            // value will do, or says nothing about it if the value is ignored
            // If you don't intend to modify the return, always return data.getLastReturnValue();
            return returnValue;
        }
    };

getHandlerName

String getHandlerName ( )

Description

Returns the name of the handler. This method doesn't need to be implemented but helps with debugging.

Parameters

This method does not receive any parameters.

Return Values

Returns the name of the handler. This method doesn't need to be implemented but helps with debugging.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

    // Create an EventHandler object which will be called when the event triggers
    EventHandler handler = new EventHandler()
    {
        /**
         * Returns the name of the handler.  This method doens't need to be implemented
         * but helps with debugging (on error executing the callback it will output this)
         */
        public String getHandlerName()
        {
            return "A test event handler";
        }

        public Object handleEvent(EventFireTime fireTime, AbstractEventData data)
        {
            // do something
        }
    };

See Also

handleEvent

Object handleEvent ( EventFireTime fireTime, AbstractEventData data )

Description

Processes the event, and potentially returns a useful value modifying something in the internal code as defined by the EventFireTime used to launch this event.

Parameters

  • fireTime Defines the methods that a fire time must have.
  • data Allows for the accessing of various data values found within ScreenScraper dependent on the class used.

Return Values

Returns a value based on which AbstractEventData class is used.

Change Log

Version Description
6.0.55a Available for all editions.

    EventHandler handler = new EventHandler()
    {  
        public String getHandlerName()
        {
            // return something
        }

        /**
         * Processes the event, and potentially returns a useful value modifying something
         * in the internal code
         *
         * @param fireTime The fire time of the event. This helps when using the same handler
         * for multiple event times, to determine which was called
         * @param data The actual data from the event. Based on the event time this
         * will be a different type. It could be SessionEventData, ScrapeableFileEventData,
         * ScriptEventData, StringEventData, etc...  It will match the fire time class name
         *
         * @return A value indicating how to proceed (or sometimes the value is ignored)
         */
        public Object handleEvent(EventFireTime fireTime, AbstractEventData data)
        {
            // While you can specifically grab any data from the data object,
            // if this is a method that has a return value that matters,
            // it's best to get it as the last return value, so that multiple
            // events can be chained together.  The input data object
            // will always have the original values for all the other getters
            Object returnValue = data.getLastReturnValue();

            // Do stuff...

            // The EventFireTime values describe in the documentation what the return
            // value will do, or says nothing about it if the value is ignored
            // If you don't intend to modify the return, always return data.getLastReturnValue();
            return returnValue;
        }
    };

See Also

AbstractEventData

The AbstractEventData class is an abstract class which allows for the accessing of various data values found within ScreenScraper. Below are the various classes that extend AbstractEventData

AbstractEventData is extended by the following classes and it is those classes that should be used in place of AbstractEventData.

getLastReturnValue

Object getLastReturnValue ( )

Description

Returns the LastReturnValue for the object. This is the value previously returned by another callback. This can be null, if no callbacks have been fired yet for this event. A null value is also the default return value for the given event.

Parameters

This method does not receive any parameters.

Return Values

Returns the LastReturnValue for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Write to Log

   // In practice AbstractEventData is just the abstract class.
   // You must actually use one of the classes that extend it.
    public Object handleEvent(EventFireTime fireTime, AbstractEventData data) {
        // While you can specifically grab any data from the data object,
                // if this is a method that has a return value that matters,
                // it's best to get it as the last return value, so that multiple
                // events can be chained together.  The input data object
                // will always have the original values for all the other getters
                Object returnValue = data.getLastReturnValue();

       
        // do something
       
        // The EventFireTime values describe in the documentation what the return
                // value will do, or says nothing about it if the value is ignored
                // If you don't intend to modify the return, always return data.getLastReturnValue();
        return data.getLastReturnValue();
    }

setLastReturnValue

void setLastReturnValue ( Object lastReturnValue )

Description

Sets the LastReturnValue fro the object.

Parameters

  • lastReturnValue The new value for the LastReturnValue

Return Values

Returns void.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

   // In practice AbstractEventData is just the abstract class.
   // You must actually use one of the classes that extend it.
    public Object handleEvent(EventFireTime fireTime, AbstractEventData data) {
               
        Object foo = // something here;
        data.setLastReturnValue(foo);
       
        // do something
       
        // The EventFireTime values describe in the documentation what the return
                // value will do, or says nothing about it if the value is ignored
                // If you don't intend to modify the return, always return data.getLastReturnValue();
        return data.getLastReturnValue();
    }

ExtractorPatternEventData

ExtractorPatternEventData extends AbstractEventData

This contains the data for various extractor pattern operations

Inherits the following methods from AbstractEventData

See Also

extractorPatternTimedOut

boolean extractorPatternEventData.extractorPatternTimedOut ( )

Description

Returns the status of the extractor pattern timeout. Returns true if and only if the extractor pattern was applied and timed out while doing so. Otherwise it will return false.

Parameters

This method does not receive any parameters.

Return Values

Returns a boolean value representing the status of the extractor pattern timeout.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Determine if an extractor pattern has timed out.

    public Object handleEvent(EventFireTime fireTime, ExtractorPatternEventData data) {
        if (data.extractorPatternTimeOut()) {
            // do something
        }
    }

getDataRecord

DataRecord extractorPatternEventData.getDataRecord ( )

Description

Returns the DataRecord value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the DataRecord value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current DataRecord.

    public Object handleEvent(EventFireTime fireTime, ExtractorPatternEventData data) {
        DataRecord dr = data.getDataRecord();
       
        // do something
    }

getDataSet

DataSet extractorPatternEventData.getDataSet ( )

Description

Returns the DataSet value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the DataSet value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current DataSet.

    public Object handleEvent(EventFireTime fireTime, ExtractorPatternEventData data) {
        DataSet ds = data.getDataSet();
       
        // do something
    }

getExtractorPattern

ExtractorPattern extractorPatternEventData.getExtractorPattern ( )

Description

Returns the ExtractorPattern value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the ExtractorPattern value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current ExtractorPattern.

    public Object handleEvent(EventFireTime fireTime, ExtractorPatternEventData data) {
        ExtractorPattern pattern = data.getExtractorPattern();
       
        // do something
    }

getScrapeableFile

ScrapeableFile extractorPatternEventData.getScrapeableFile ( )

Description

Returns the Scrapeablefile value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Scrapeablefile value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current ScrapeableFile.

    public Object handleEvent(EventFireTime fireTime, ExtractorPatternEventData data) {
        ScrapeableFile sf = data.getScrapeableFile();
       
        // do something
    }

getSession

ScrapingSession extractorPatternEventData.getSession ( )

Description

Returns the Session value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Session value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current Session.

    public Object handleEvent(EventFireTime fireTime, ExtractorPatternEventData data) {
        ScrapingSession _session = data.getSession();
       
        // do something
    }

ScrapeableFileEventData

ScrapeableFileEventData extends AbstractEventData

This contains the data for various scrapeable file operations

Inherits the following methods from AbstractEventData

See Also

getHttpResponseData

String scrapeableFileEventData.getHttpResponseData ( )

Description

Returns the HttpResponseData for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the HttpResponseData for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the HttpResponseData

    public Object handleEvent(EventFireTime fireTime, ScrapeableFileEventData data) {
        String responseData = data.getHttpResponseData();
       
        // do something
    }

getRedirectRequestBuilder

ScrapingRequest.Builder scrapeableFileEventData.getRedirectRequestBuilder ( )

Description

Returns the RedirectRequestBuilder for the object. Use this to add headers, etc... for the redirect. It can be null depending on the HTTP client being used, and whether or not it supports manually playing with the redirect.

Parameters

This method does not receive any parameters.

Return Values

Returns the RedirectRequestBuilder for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the Request Builder in order to modify it.

    public Object handleEvent(EventFireTime fireTime, ScrapeableFileEventData data) {
        ScrapingRequest.Builder builder = data.getRedirectRequestBuilder();
       
        // do something
    }

getScrapeableFile

ScrapeableFile scrapeableFileEventData.getScrapeableFile ( )

Description

Returns the Scrapeablefile value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Scrapeablefile value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current ScrapeableFile.

    public Object handleEvent(EventFireTime fireTime, ScrapeableFileEventData data) {
        ScrapeableFile sf = data.getScrapeableFile();
       
        // do something
    }

getSession

ScrapingSession scrapeableFileEventData.getSession ( )

Description

Returns the Session value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Session value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current Session.

    public Object handleEvent(EventFireTime fireTime, ScrapeableFileEventData data) {
        ScrapingSession _session = data.getSession();
       
        // do something
    }

ScriptEventData

ScriptEventData extends AbstractEventData

This contains the data for various script operations

Inherits the following methods from AbstractEventData

See Also

getDataRecord

DataRecord scriptEventData.getDataRecord ( )

Description

Returns the DataRecord value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the DataRecord value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current DataRecord.

    public Object handleEvent(EventFireTime fireTime, ScriptEventData data) {
        DataRecord dr = data.getDataRecord();
       
        // do something
    }

getDataSet

DataSet scriptEventData.getDataSet ( )

Description

Returns the DataSet value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the DataSet value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current DataSet.

    public Object handleEvent(EventFireTime fireTime, ScriptEventData data) {
        DataSet ds = data.getDataSet();
       
        // do something
    }

getScrapeableFile

ScrapeableFile scriptEventData.getScrapeableFile ( )

Description

Returns the Scrapeablefile value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Scrapeablefile value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current ScrapeableFile.

    public Object handleEvent(EventFireTime fireTime, ScriptEventData data) {
        ScrapeableFile sf = data.getScrapeableFile();
       
        // do something
    }

getScriptException

java.lang.Exception scriptEventData.getScriptException ( )

Description

Returns the ScriptException for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the ScriptException for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the script exception

    public Object handleEvent(EventFireTime fireTime, ScriptEventData data) {
        java.lang.Exception e = data.getScriptException();
       
        // do something
    }

getScriptName

String scriptEventData.getScriptName ( )

Description

Returns the ScriptName value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the ScriptName value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the script name

    public Object handleEvent(EventFireTime fireTime, ScriptEventData data) {
         String name = data.getScriptName();
       
        // do something
    }

getSession

ScrapingSession scriptEventData.getSession ( )

Description

Returns the Session value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Session value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current Session.

    public Object handleEvent(EventFireTime fireTime, ScriptEventData data) {
        ScrapingSession _session = data.getSession();
       
        // do something
    }

SessionEventData

SessionEventData extends AbstractEventData

This contains the data for various session operations

Inherits the following methods from AbstractEventData

See Also

getIncrementRecordsAmount

Object sessionEventData.getIncrementRecordsAmount ( )

Description

Returns the IncrementRecordsAmount value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the IncrementRecordsAmount value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current increment records amount.

    public Object handleEvent(EventFireTime fireTime, SessionEventData data) {
        Object recordsAmt = data.getIncrementRecordsAmount();
       
        // do something
    }

getSession

ScrapingSession sessionEventData.getSession ( )

Description

Returns the Session value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Session value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current Session.

    public Object handleEvent(EventFireTime fireTime, SessionEventData data) {
        ScrapingSession _session = data.getSession();
       
        // do something
    }

getVariableName

String sessionEventData.getVariableName ( )

Description

Returns the VariableName value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the VariableName value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the variable name.

    public Object handleEvent(EventFireTime fireTime, SessionEventData data) {
        String name = data.getVariableName();
       
        // do something
    }

getVariableValue

Object sessionEventData.getVariableValue ( )

Description

Returns the VariableValue value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the VariableValue value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Get the current Session.

    public Object handleEvent(EventFireTime fireTime, SessionEventData data) {
        Object value = data.getVariableValue();
       
        // do something
    }

StringEventData

StringEventData extends AbstractEventData

This contains the data for various string operations

Inherits the following methods from AbstractEventData

See Also

getInput

String stringEventData.getInput ( )

Description

Returns the Input value for the object.

Parameters

This method does not receive any parameters.

Return Values

Returns the Input value for the object.

Change Log

Version Description
6.0.55a Available for all editions.

Examples

Write to Log

    public Object handleEvent(EventFireTime fireTime, StringEventData data) {
        String str = data.getInput();
       
        // do something
    }