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: <whate...@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: whate...@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:
whate...@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:
whate...@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: [email protected]
For additional commands, e-mail: [email protected]
