NAME

BuildForge::Services::DBO::FilterPattern


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        $pattern = new BuildForge::Services::DBO::FilterPattern($conn);
        # Getter / setter functions
        $filterId = $pattern->getFilterId();
        $ordinal = $pattern->getPatternOrdinal();;
        $patternRegex = $pattern->getPattern();
        $action = $pattern->getAction();
        $accessGroupId = $pattern->getNotification();
        $pattern->setPattern('Pattern to match');
        $pattern->setAction(ENUM_FILTERPATTERN_ACTION->CLEAR_AND_HALT);
        $pattern->setNotification($accessGroupId);
        $pattern->update();
        
        # Pattern creation, modification, and deletion.
        $envGroup = BuildForge::Services::DBO::Filter->findById($conn, filterId);
        $newpattern = new BuildForge::Services::DBO::FilterPattern($conn);
        $newpattern->setPattern('New pattern to match');
        $envGroup->addFilterPattern($var);
        $newpattern->setPattern('Different pattern');
        $newpattern->update();
        
        $newpattern2 = $newpattern->clone();
        $envGroup->addFilterPattern($newpattern2);
        
        $newpattern->moveTo(2);
        $newpattern->delete();
                
        $conn->logout;
        $conn->close;


DESCRIPTION

FilterPattern allows you to create and modify filter pattens inside of a Filter. To create the patterns in the database, see the Filter->addFilterPattern() function.


METHODS

new BuildForge::Services::DBO::FilterPattern(connection, {filter}, {FilterPatternParamsHashRef})

Returns a new instance of an FilterPattern object.

connection

A connected BuildForge::Services::Connection object.

filter

This should be undef or not passed - it is only used internally.

FilterPatternParamsHashRef

An optional reference to a hash containing any or all of the following fields.

pattern

The filter pattern itself.

action

The pattern's action when a log line matches the pattern. This may be any of:

FAIL

The default. Will cause the step to fail (if not first cleared).

CLEAR

Causes the step to lose failure status. Has no effect on warning status.

CLEAR_AND_HALT

Causes the step to lose failure status and the filter set to stop processing the current log line and go on to the next.

FAIL_AND_HALT

Causes the step to fail and the filter set to stop processing the current log line and go on to the next.

HALT

Causes the filter set to stop processing the current log line and go on to the next.

WARNING

Causes the step to pass with warning status if it doesn't end in failure.

CLEAR_WARNING

Clears the warning status of the step. Has no effect on failure status.

CLEAR_WARNING_AND_HALT

Clears the warning status of the step and causes the filter set to stop processing the current log line and go on to the next.

NOTIFY_CHANGERS

If the project has an adaptor attached which saves changed file information and the people who changed it, this notifies the people that changed the build data that this filter has been matched.

INCLUDE

Includes another filter set inside this one. If this is set, the filter pattern must be the name of the filter set to be included.

notification

The access group ID (from $accessGroup->getLevel()) for the notification group for this pattern. If the pattern is matched on a step, the engine sends a notification email to all members of the access group.

$pattern->clone()

A copy of the FilterPattern object is returned without affecting the database. To save the copy to an filter group, $filter->addFilterPattern($copy) must be run on the copy.

$pattern->update()

Updates the pattern settings in the database.

$pattern->moveTo(index)

Moves the pattern within its parent filter group.

index

The new location of the pattern. 0 moves it to the first position, 1 to the second position, etc.

$pattern->delete()

Deletes the pattern from the database.

$pattern->getParent()

Returns the BuildForge::Services::DBO::Filter object for the filter group this pattern belongs to.

$pattern->getFilterId()

Returns the filter group ID for the filter group this pattern belongs to.

$pattern->getPatternOrdinal()

Returns the ordinal for the position of the pattern in the pattern list. 1 means it's the first pattern, 2 means it's the second, etc.

$pattern->getPattern()

Returns the actual pattern.

$pattern->getAction()

Returns the pattern action which controls how the pattern value is set. This may be any of 'CLEAR', 'CLEAR_AND_HALT', 'FAIL', 'FAIL_AND_HALT', 'HALT', 'INCLUDE', 'WARNING', 'CLEAR_WARNING', 'CLEAR_WARNING_AND_HALT', or 'NOTIFY_CHANGERS'.

$pattern->getNotification()

Returns the notification group for this pattern. If the pattern is matched on a step, the engine sends a notification email to all members of the access group.

$pattern->setPattern(value)

Sets the value of the pattern. $pattern->update() must be run before changes are replicated in the database.

value

The new regular expression.

$pattern->setAction(action)

Sets the pattern action which controls how the filter reacts when a match is found in a log line. $pattern->update() must be run before changes are replicated in the database.

action

May be any of:

FAIL

Will cause the step to fail (if not first cleared).

CLEAR

Causes the step to lose failure status. Has no effect on warning status.

CLEAR_AND_HALT

Causes the step to lose failure status and the filter set to stop processing the current log line and go on to the next.

FAIL_AND_HALT

Causes the step to fail and the filter set to stop processing the current log line and go on to the next.

HALT

Causes the filter set to stop processing the current log line and go on to the next.

WARNING

Causes the step to pass with warning status if it doesn't end in failure.

CLEAR_WARNING

Clears the warning status of the step. Has no effect on failure status.

CLEAR_WARNING_AND_HALT

Clears the warning status of the step and causes the filter set to stop processing the current log line and go on to the next.

NOTIFY_CHANGERS

If the project has an adaptor attached which saves changed file information and the people who changed it, this notifies the people that changed the build data that this filter has been matched.

INCLUDE

Includes another filter set inside this one. If this is set, the filter pattern must be the name of the filter set to be included.

$pattern->setNotification(accessGroupId)

Sets the notification group for this pattern. If the pattern is matched on a step, the engine sends a notification email to all members of the access group. $pattern->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID for the access group to be notified, from $accessGroup->getLevel().


COPYRIGHT

Copyright (c)2006-2007 International Business Machines, Inc. All rights reserved.