james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From e...@apache.org
Subject svn commit: r1027964 - in /james/server/trunk/src/site/xdoc: dev_extend_hook_smtp.xml dev_smtp_hooks.xml
Date Wed, 27 Oct 2010 13:52:05 GMT
Author: eric
Date: Wed Oct 27 13:52:05 2010
New Revision: 1027964

URL: http://svn.apache.org/viewvc?rev=1027964&view=rev
Log:
Format page.

Added:
    james/server/trunk/src/site/xdoc/dev_extend_hook_smtp.xml
      - copied, changed from r1027921, james/server/trunk/src/site/xdoc/dev_smtp_hooks.xml
Removed:
    james/server/trunk/src/site/xdoc/dev_smtp_hooks.xml

Copied: james/server/trunk/src/site/xdoc/dev_extend_hook_smtp.xml (from r1027921, james/server/trunk/src/site/xdoc/dev_smtp_hooks.xml)
URL: http://svn.apache.org/viewvc/james/server/trunk/src/site/xdoc/dev_extend_hook_smtp.xml?p2=james/server/trunk/src/site/xdoc/dev_extend_hook_smtp.xml&p1=james/server/trunk/src/site/xdoc/dev_smtp_hooks.xml&r1=1027921&r2=1027964&rev=1027964&view=diff
==============================================================================
--- james/server/trunk/src/site/xdoc/dev_smtp_hooks.xml (original)
+++ james/server/trunk/src/site/xdoc/dev_extend_hook_smtp.xml Wed Oct 27 13:52:05 2010
@@ -25,85 +25,130 @@
 
 <body>
 
-   The JAMES SMTP Server Component allows to easy write your own code which will get executed
in the SMTP-Transaction. Thats a bit different then using a Mailet a.k.a Mailet-API. As
-your code will get executed before the mail was even accepted. This can help you in many
ways, most times its used for rejecting SPAM/Junk within the SMTP-Dialog. But it can be used
for other
-things too. Its up to you and your use case. 
-
-But be aware as your code needs to get executed during the SMTP-Transaction it should not
take to long to execute. As it will need to fit in before the timeout was hit which can be
different
-on every mailserver. But as a general rule as long as your code can get executed within 30
seconds it should be fine.
-
-  <section name="James 3.0-M1">
+  <section name="Introduction to SMTP Hooks">
   
+    <p>The James SMTP Server Component allows to easy write your own code which will
get executed 
+       in the SMTP-Transaction. Thats a bit different then using a Mailet a.k.a Mailet-API.</p>
+      
+    <p>As your code will get executed before the mail was even accepted. This can help
you in many ways,
+       most times its used for rejecting SPAM/Junk within the SMTP-Dialog. But it can be
used for 
+       other things too.</p>
+      
+    <p>Its up to you and your use case.</p>
+
+    <p>But be aware as your code needs to get executed during the SMTP-Transaction
it should not 
+       take to long to execute. As it will need to fit in before the timeout was hit which
can be 
+       different on every mailserver. But as a general rule as long as your code can get
executed 
+       within 30 seconds it should be fine.</p>
+      
+  </section>
 
--===== Hooks =====-
+  <section name="Supported Hooks in James Server">
+  
+    <p>The James SMTP Server comes with a few interfaces which helps you to "hook-in"
a 
+       specific SMTP Command. That means your class which implements the given interface(s)
will get
+       called after the SMTP-Command was parsed and depending on your implementation it will
handle it.</p>
+
+    <p>In detail the following hooks are supported:</p>
+
+    <subsection name="AuthHook">
+      <p>Allows to hook in your code for authenticate users for sending mail via SMTP
AUTH. 
+      You could for example query your own database table to see if a user should be allowed
to 
+      send mail with the given username and password.</p>
+    </subsection>
+
+    <subsection name="ConnectionHandler">
+      <p>Allows to hook in your code on a new connection. So you could just drop it

+      or do something else.</p>
+    </subsection>
+ 
+    <subsection name="HeloHook">
+      <p>Allows to hook in your code in the HELO and EHLO commands.</p>
+    </subsection>
+
+    <subsection name="MailHook">
+      <p>Allows to hook in your code in the MAIL command. Like checking the sender

+      which was given with MAIL FROM: &lt;whatever@example&gt;</p>
+    </subsection>
+
+    <subsection name="MailParametersHook">
+      <p>Allows to hook in given parameters in the EHLO command.</p>
+    </subsection>
+
+    <subsection name="JamesMessageHook">
+
+      <p>Allow to hook in your code after the email was received via the DATA command
and 
+      was marked for queuing by the CLRF.CRLF sequence. This will get executed right before

+      the message will actual get queued.</p>
+      
+      <p>IMPORTANT: If you want to do heavy processing here 
+      and not want to reject the method based on a criteria you are most times better of
to 
+      use the Mailet API!</p>
+
+    </subsection>
+
+    <subsection name="QuitHook">
+      <p>Allow to hook in your code in the QUIT command.</p>
+    </subsection>
+
+    <subsection name="RcptHook">
+      <p>Allows to hook in your code in the RCPT command. Like implementing a custom
logic to 
+      check if the mail for a given recipient should get accepted or rejected.</p>
+    </subsection>
+
+    <subsection name="UnknownCmdHook">
+      <p>Allows to hook in your code on every unknown command.</p>
+    </subsection>
 
-The JAMES SMTP Server comes with a few interfaces which helps you to "hook-in" a specific
SMTP Command. That means your class which implements the given interface(s) will get
-called after the SMTP-Command was parsed and depending on your implementation it will handle
it.
+  </section>
 
-In detail the following hooks are supported:
+  <section name="Return-Codes">
 
- * AuthHook
- Allows to hook in your code for authenticate users for sending mail via SMTP AUTH. You could
for example query your own database table to see if a user should be allowed to 
- send mail with the given username and password
+    <p>Each of the above mention Hooks need to return a HookResult to tell the SMTPServer

+    if the next registered Hook should get called or not.</p>
+    
+    <p>For this the HookReturnCode is used.</p>
 
-* ConnectionHandler
-Allows to hook in your code on a new connection. So you could just drop it or do something
else 
+  </section>
  
-* HeloHook
-Allows to hook in your code in the HELO and EHLO commands.
-
-* MailHook
-Allows to hook in your code in the MAIL command. Like checking the sender which was given
with MAIL FROM: whatever@example
-
-* MailParametersHook
-Allows to hook in given parameters in the EHLO command
-
-* JamesMessageHook
-Allow to hook in your code after the email was received via the DATA command and was marked
for queuing by the CLRF.CRLF sequence. This will get executed right before the message
-will actual get queued. IMPORTANT: If you want to do heavy processing here and not want to
reject the method based on a criteria you are most times better of to use the Mailet API!
-
-
-* QuitHook
-Allow to hook in your code in the QUIT command. 
+  <section name="Custom Hooks Implementations">
 
+    <subsection name="Why a Custom Hook">
 
-* RcptHook
-Allows to hook in your code in the RCPT command. Like implementing a custom logic to check
if the mail for a given recipient should get accepted or rejected
+      <p>What to do if the Hook API is not enough for you ? You want for example 
+         to write a code which handles a new command like "YOURCOOLCOMMAND: whatever@example".</p>
+    
+      <p>For this kind of needs you should implement the CommandHandler interface.

+         This gives you a lower-level API to handle this kind of tasks. If you want 
+         to support a custom Hook in your CommandHandler its the best
+         to just extend AbstractHookableCmdHandler.</p>
+         
+    </subsection>
 
-* UnknownCmdHook
-Allows to hook in your code on every unknown command. 
+    <subsection name="Things to Remember ">
 
-
-* Return-Codes
- Each of the above mention Hooks need to return a HookResult to tell the SMTPServer if the
next registered Hook should get called or not. For this the HookReturnCode is used. 
+      <p>Be aware that your implementation needs to be thread-safe as it will get used
as singleton. 
+         If you need to store temporary informations within the SMTP Transaction/Session
you should
+         use the SMTPSession.getState().put(...) and SMTPSession.getConnectionState().put(...)
methods.</p>
  
--=======================-
+      <p>For a more explanation see the <a href="apidocs/index.html">apidocs</a>
for the protocols library which
+         is used by James SMTPServer.</p>
 
- 
- 
- -===== Advanced implementations =====--
- What to do if the Hook API is not enough for you ? You want for example to write a code
which handles a new command like "YOURCOOLCOMMAND: whatever@example". For this kind of needs
- you should implement the CommandHandler interface. This gives you a lower-level API to handle
this kind of tasks. If you want to support a custom Hook in your CommandHandler its the best
- to just extend AbstractHookableCmdHandler.
- 
- 
--==== Things to remember ============-
- Be aware that your implementation needs to be thread-safe as it will get used as singleton.
If you need to store temporary informations within the SMTP Transaction/Session you should
- use the SMTPSession.getState().put(...) and SMTPSession.getConnectionState().put(...) methods.
- 
- For a more explanation see the apidocs for the protocols library which is used by JAMES
SMTPServer 
- -===============================-
+    </subsection>
 
+    <subsection name="Get your Hook implementations loaded">
+  
+      <p>Just create a jar file which contains your code and put it in /path/to/james/conf/lib/

+      folder. The jar will get picked up by the ClassLoader automatic then.</p>
+    
+      <p>After that open the smtpserver.xml file and add your hook to the <code>&lt;handlers&gt;&lt;/handlers&gt;</code>
block in the order you 
+       want to have it executed. So if you have 2 MailHook implementation make sure the first
one 
+       which is listed in smtpserver.xml is the one you want to call first.</p>
 
--===== How to get your implementation loaded after you wrote it =======-
-Just create a jar file which contains your code and put it in /path/to/james/conf/lib/ folder.
The jar will get picked up by the ClassLoader automatic then. After that open the
-smtpserver.xml file and add your hook to the <handlers></handlers> block in the
order you want to have it executed. So if you have 2 MailHook implementation make sure the
first one 
-which is listed in smtpserver.xml is the one you want to call first.
-
+    </subsection>
 
- 
   </section>
-
+ 
 </body>
 
 </document>



---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message