You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by er...@apache.org on 2010/10/27 15:52:05 UTC
svn commit: r1027964 - in /james/server/trunk/src/site/xdoc:
dev_extend_hook_smtp.xml dev_smtp_hooks.xml
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: <whatever@example></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><handlers></handlers></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