<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Class: P4Trigger</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel=StyleSheet href=".././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript" language="JavaScript">
<!--
function popCode(url) {
window.open(url, "Code",
"resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
//-->
</script>
</head>
<body bgcolor="white">
<table summary="Information on class" width="100%" border="0" cellspacing="0">
<tr class="title-row">
<td class="big-title-font">
<sup><font color="aqua">Class</font></sup> P4Trigger
</td>
<td align="right">
<table summary="layout" cellspacing="0" cellpadding="2">
<tr valign="top">
<td class="small-title-font">In:</td>
<td class="small-title-font">
<a href="../files/P4Triggers_rb.html" class="aqua">
P4Triggers.rb
</a>
<br />
</td>
</tr>
<tr>
<td class="small-title-font">Parent:</td>
<td class="small-title-font">
Object
</td>
</tr>
</table>
</td>
</tr>
</table>
<!-- banner header -->
<div class="description"><p>
A class providing a generic framework for all triggers. It provides
rudimentary error handling so all errors get logged to stderr, and we also
have a method for reporting a more friendly message to the user. It is
intended that all trigger scripts will derive their own subclass of <a
href="P4Trigger.html">P4Trigger</a> and override/expand it as necessary.
</p>
<p>
You must override the validate() method if you want your trigger to work.
The default implementation accepts <b>everything</b> so make sure you
provide a method to reject bad changes or you will have accomplished
nothing.
</p>
</div>
<table summary="Methods" cellpadding="5" width="100%">
<tr><td class="tablesubtitle">Methods</td></tr>
</table>
<div class="name-list">
<a href="#M000025">error_message</a>
<a href="#M000022">get_change</a>
<a href="#M000024">message</a>
<a href="#M000020">new</a>
<a href="#M000021">parse_change</a>
<a href="#M000023">validate</a>
</div>
<table summary="Attributes" cellpadding="5" width="100%">
<tr><td class="tablesubtitle">Attributes</td></tr>
</table>
<table summary="Attribute details" cellspacing="5">
<tr valign="top">
<td class="attr-name">change</td>
<td align="center" class="attr-rw"> [R] </td>
<td><p>
Direct access to the changelist in question. Returns a <a
href="P4Change.html">P4Change</a> object
</p>
</td>
</tr>
<tr valign="top">
<td class="attr-name">p4</td>
<td align="center" class="attr-rw"> [R] </td>
<td><p>
Direct access to the <a href="P4.html">P4</a> object. You can use this for
interrogating the Perforce server. It’s in parse_forms() mode and has
an exception_level of 1 so exceptions will only be raised on errors, not
warnings.
</p>
</td>
</tr>
</table>
<table summary="Method list" cellpadding="5" width="100%">
<tr><td class="tablesubtitle">Public Class methods</td></tr>
</table>
<table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0">
<tr><td class="methodtitle">
<a name="M000020"></a>
<b>new</b>()
</td></tr>
</table>
<div class="description">
<p>
Constructor.
</p>
</div>
<pre class="source">
<span class="cmt"># File P4Triggers.rb, line 159</span>
<span class="kw">def</span> initialize
@change = <span class="kw">nil</span>
@p4 = P4.new
@p4.parse_forms
@p4.exception_level = 1
<span class="kw">begin</span>
@p4.connect
<span class="kw">rescue</span> P4Exception
error_message()
raise
<span class="kw">end</span>
<span class="kw">end</span>
</pre>
<table summary="Method list" cellpadding="5" width="100%">
<tr><td class="tablesubtitle">Public Instance methods</td></tr>
</table>
<table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0">
<tr><td class="methodtitle">
<a name="M000021"></a>
<b>parse_change</b>( change_no )
</td></tr>
</table>
<div class="description">
<p>
The main execution phase of the trigger. We assume since this is a
pre-submit trigger that there will be a changelist involved. The steps for
most triggers are common:
</p>
<ol>
<li>Find out about the changelist
</li>
<li>Enforce the rules
</li>
</ol>
<p>
We try to generalise this process so this class calls <a
href="P4Trigger.html#M000022">get_change</a>() for step 1, and validate()
for step 2. Subclasses may override these methods to tailor the
trigger’s behaviour
</p>
<p>
<a href="P4Trigger.html#M000021">parse_change</a>() returns the correct
exit status for the trigger so you would normally use it like this:
</p>
<pre>
exit( trig.parse_change( change_no ) )
</pre>
</div>
<pre class="source">
<span class="cmt"># File P4Triggers.rb, line 197</span>
<span class="kw">def</span> parse_change( change_no )
<span class="kw">begin</span>
<span class="kw">if</span> ( ! change_no )
raise( <span class="str">"No changelist number supplied to trigger script.\n"</span> +
<span class="str">"Please check your trigger configuration."</span>
)
<span class="kw">end</span>
get_change( change_no )
<span class="kw">return</span> ( validate() ? 0 : 1 )
<span class="kw">rescue</span>
<span class="cmt"># Report errors to stderr, so they go into the Perforce server's</span>
<span class="cmt"># logfile and report a simpler message to stdout</span>
$stderr.puts( <span class="str">"\nError during trigger execution:\n\n"</span> )
<span class="kw">if</span> ( $!.kind_of?( P4Exception ) )
p4.errors.each { |e| $stderr.puts( e ) }
<span class="kw">else</span>
$stderr.puts( $!.to_s )
<span class="kw">end</span>
$stderr.puts( <span class="str">"\nStack Trace:\n"</span> )
$stderr.puts( $!.backtrace )
$stdout.puts( error_message() )
<span class="cmt"># Now we return false to the caller so they can return with </span>
<span class="cmt"># the correct exit status</span>
<span class="kw">return</span> 1
<span class="kw">end</span>
<span class="kw">end</span>
</pre>
<table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0">
<tr><td class="methodtitle">
<a name="M000022"></a>
<b>get_change</b>( change_no )
</td></tr>
</table>
<div class="description">
<p>
The default implementation of <a
href="P4Trigger.html#M000022">get_change</a>. Returns a hash describing the
change based on an execution of "p4 describe -s". The hash is
also saved in the @change member which subclasses may access in their
validate() method. For most triggers this will be sufficient.
</p>
</div>
<pre class="source">
<span class="cmt"># File P4Triggers.rb, line 229</span>
<span class="kw">def</span> get_change( change_no )
@change = p4.run_describe( <span class="str">"-s"</span>, change_no )
<span class="kw">end</span>
</pre>
<table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0">
<tr><td class="methodtitle">
<a name="M000023"></a>
<b>validate</b>()
</td></tr>
</table>
<div class="description">
<p>
The default implementation of validate(). Very simple, it accepts
everything. You are expected to override this method with one of your own.
When you do so, you can use the @change member to get at the details of the
change you’re validating.
</p>
</div>
<pre class="source">
<span class="cmt"># File P4Triggers.rb, line 237</span>
<span class="kw">def</span> validate()
<span class="kw">true</span>
<span class="kw">end</span>
</pre>
<table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0">
<tr><td class="methodtitle">
<a name="M000024"></a>
<b>message</b>( string )
</td></tr>
</table>
<div class="description">
<p>
Method to send a message to the user. Just writes to stdout, but it’s
nice to encapsulate that here.
</p>
</div>
<pre class="source">
<span class="cmt"># File P4Triggers.rb, line 245</span>
<span class="kw">def</span> message( string )
$stdout.print( string )
<span class="kw">end</span>
</pre>
<table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0">
<tr><td class="methodtitle">
<a name="M000025"></a>
<b>error_message</b>()
</td></tr>
</table>
<div class="description">
<p>
Default message for when things go wrong
</p>
</div>
<pre class="source">
<span class="cmt"># File P4Triggers.rb, line 250</span>
<span class="kw">def</span> error_message()
<span class="str">"An error was encountered during trigger execution. Please\n"</span> +
<span class="str">"contact your Perforce administrator and ask them to\n"</span> +
<span class="str">"investigate the cause of this error\n"</span>
<span class="kw">end</span>
</pre>
</body>
</html> | # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #3 | 4654 | Tony Smith |
Add an example spec trigger to show how you might restrict the default view for all new clients to a pre-defined set of mappings. |
||
| #2 | 4640 | Tony Smith |
Add a sample post-commit trigger that can be used to keep a master and slave branch in sync. |
||
| #1 | 3637 | Tony Smith | Add RDoc documentation to the sample triggers. |