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 da...@apache.org on 2002/11/27 02:59:23 UTC
cvs commit: jakarta-james/proposals/imap2/test/org/apache/james/test AbstractProtocolTest.java FileProtocolSessionBuilder.java ProtocolSession.java SimpleFileProtocolTest.java InvalidServerResponseException.java JamesTask.java
darrell 2002/11/26 17:59:23
Modified: proposals/imap2/test/org/apache/james/imapserver
CommandParserTest.java ImapHostTest.java
ImapStoreTest.java InitialMail.java
TestAuthenticated.java TestNonAuthenticated.java
TestSelected.java
proposals/imap2/test/org/apache/james/remotemanager
InitialImapUsersTest.java UserManagementTest.java
proposals/imap2/test/org/apache/james/test
AbstractProtocolTest.java
FileProtocolSessionBuilder.java
ProtocolSession.java SimpleFileProtocolTest.java
Added: proposals/imap2/test/org/apache/james/imapserver
ImapTest.java
Removed: proposals/imap2/test/org/apache/james/imapserver
IMAPTest.java
proposals/imap2/test/org/apache/james/test
InvalidServerResponseException.java JamesTask.java
Log:
Bunch of javadoc updates
Revision Changes Path
1.3 +7 -1 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/CommandParserTest.java
Index: CommandParserTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/CommandParserTest.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- CommandParserTest.java 26 Nov 2002 14:53:48 -0000 1.2
+++ CommandParserTest.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -143,6 +143,12 @@
assertEquals( "INBOX", parser.mailbox( request ));
}
+ /**
+ * Builds and ImapRequestLineReader with the specified string, using {@link #writer}
+ * as the server writer for command continuation requests
+ * @param testRequest A string containing client requests.
+ * @return An initialised ImapRequestLineReader
+ */
private ImapRequestLineReader getRequest( String testRequest )
{
BufferedReader reader = new BufferedReader( new StringReader( testRequest ) );
1.3 +21 -1 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/ImapHostTest.java
Index: ImapHostTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/ImapHostTest.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ImapHostTest.java 26 Nov 2002 14:53:48 -0000 1.2
+++ ImapHostTest.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -55,6 +55,9 @@
return new JamesImapHost( new InMemoryStore() );
}
+ /**
+ * Tests creation of mailboxes in user's personal space. No namespaces are used.
+ */
public void testCreatePersonal() throws Exception
{
// Create a single mailbox.
@@ -83,6 +86,10 @@
assertMailbox( "this.is.yet.another.mailbox", true );
}
+ /**
+ * Tests deletion of mailboxes in user's personal space. No namespaces are used.
+ * @throws Exception
+ */
public void testDelete() throws Exception
{
// Simple create/delete
@@ -119,6 +126,10 @@
assertNoMailbox( "one" );
}
+ /**
+ * Checks that a mailbox with the supplied name exists, and that its
+ * NoSelect flag matches that expected.
+ */
private void assertMailbox( String name, boolean selectable ) throws MailboxException
{
ImapMailbox mailbox = imapHost.getMailbox( user, name );
@@ -136,6 +147,9 @@
}
}
+ /**
+ * Asserts that a mailbox with the supplied name doesn't exist.
+ */
private void assertNoMailbox( String name ) throws Exception
{
ImapMailbox mailbox = imapHost.getMailbox( user, name );
@@ -143,11 +157,17 @@
mailbox );
}
+ /**
+ * Calls {@link ImapHost#createMailbox} with the specified name and the test user.
+ */
private ImapMailbox create( String name ) throws Exception
{
return imapHost.createMailbox( user, name );
}
+ /**
+ * Calls {@link ImapHost#deleteMailbox} with the specified name and the test user.
+ */
private void delete( String name ) throws Exception
{
imapHost.deleteMailbox( user, name );
1.3 +37 -1 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/ImapStoreTest.java
Index: ImapStoreTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/ImapStoreTest.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ImapStoreTest.java 26 Nov 2002 14:53:48 -0000 1.2
+++ ImapStoreTest.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -48,6 +48,9 @@
return new InMemoryStore();
}
+ /**
+ * Tests creation of mailboxes in the Store.
+ */
public void testCreate() throws Exception
{
// Get the user namespace.
@@ -77,6 +80,9 @@
catch ( MailboxException e ) {}
}
+ /**
+ * Tests deletion of mailboxes from the store.
+ */
public void testDelete() throws Exception
{
// Simple create/delete
@@ -108,6 +114,9 @@
assertNoMailbox( "one.two" );
}
+ /**
+ * Tests the {@link ImapStore#listMailboxes} method.
+ */
public void testListMailboxes() throws Exception
{
Collection coll;
@@ -151,6 +160,10 @@
}
+ /**
+ * Asserts that the supplied collection contains exactly the mailboxes in the
+ * array provided.
+ */
private void assertContents( Collection coll, ImapMailbox[] imapMailboxes )
throws Exception
{
@@ -161,6 +174,11 @@
}
}
+
+ /**
+ * Checks that a mailbox with the supplied name exists, and that its
+ * NoSelect flag matches that expected.
+ */
private void assertMailbox( String name, boolean selectable )
{
ImapMailbox mailbox = imapStore.getMailbox( prefixUserNamespace( name ) );
@@ -178,6 +196,9 @@
}
}
+ /**
+ * Asserts that a mailbox with the supplied name doesn't exist.
+ */
private void assertNoMailbox( String name )
{
ImapMailbox mailbox = imapStore.getMailbox( prefixUserNamespace( name ));
@@ -185,29 +206,44 @@
mailbox );
}
+ /**
+ * Creates a mailbox with the specified name in the root user namespace.
+ */
private ImapMailbox create( String name ) throws Exception
{
ImapMailbox root = imapStore.getMailbox( USER_NAMESPACE );
return create( root, name );
}
+ /**
+ * Creates a mailbox under the parent provided with the specified name.
+ */
private ImapMailbox create( ImapMailbox parent, String name )
throws MailboxException
{
return imapStore.createMailbox( parent, name, true );
}
+ /**
+ * Deletes a mailbox from the store.
+ */
private void delete( String name ) throws MailboxException
{
ImapMailbox mailbox = imapStore.getMailbox( prefixUserNamespace( name ) );
imapStore.deleteMailbox( mailbox );
}
+ /**
+ * Executes {@link ImapStore#listMailboxes} with the supplied pattern.
+ */
private Collection list( String pattern ) throws MailboxException
{
return imapStore.listMailboxes( prefixUserNamespace( pattern ) );
}
+ /**
+ * Prefixes a mailbox name with the "#mail" namespace.
+ */
private String prefixUserNamespace( String name )
{
return USER_NAMESPACE + HIERARCHY_DELIMITER + name;
1.3 +4 -1 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/InitialMail.java
Index: InitialMail.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/InitialMail.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- InitialMail.java 26 Nov 2002 14:53:48 -0000 1.2
+++ InitialMail.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -16,8 +16,11 @@
import javax.mail.internet.MimeMessage;
import java.util.Properties;
+/**
+ * Sets up some intial mail which is used in the Imap test cases.
+ */
public final class InitialMail extends TestCase
- implements IMAPTest
+ implements ImapTest
{
private Session _session;
private InternetAddress _fromAddress;
1.3 +14 -2 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/TestAuthenticated.java
Index: TestAuthenticated.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/TestAuthenticated.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TestAuthenticated.java 26 Nov 2002 14:53:48 -0000 1.2
+++ TestAuthenticated.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -12,14 +12,22 @@
import junit.framework.Test;
import junit.framework.TestSuite;
+/**
+ * Runs tests for commands valid in the AUTHENTICATED state. A login session precedes
+ * the execution of the test elements.
+ */
public class TestAuthenticated
- extends SimpleFileProtocolTest implements IMAPTest
+ extends SimpleFileProtocolTest implements ImapTest
{
public TestAuthenticated( String name )
{
super( name );
}
+ /**
+ * Sets up {@link #preElements} with a welcome message and login request/response.
+ * @throws Exception
+ */
public void setUp() throws Exception
{
super.setUp();
@@ -30,9 +38,13 @@
protected void addLogin( String username, String password )
{
testElements.CL( "a001 LOGIN " + username + " " + password );
- testElements.SL( "a001 OK LOGIN completed" );
+ testElements.SL( "a001 OK LOGIN completed", "TestAuthenticated.java:33" );
}
+ /**
+ * Provides all tests which should be run in the authenicated state. Each test name
+ * corresponds to a protocol session file.
+ */
public static Test suite() throws Exception
{
TestSuite suite = new TestSuite();
1.3 +11 -0 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/TestNonAuthenticated.java
Index: TestNonAuthenticated.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/TestNonAuthenticated.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TestNonAuthenticated.java 26 Nov 2002 14:53:48 -0000 1.2
+++ TestNonAuthenticated.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -12,6 +12,10 @@
import junit.framework.Test;
import junit.framework.TestSuite;
+/**
+ * Runs tests for commands valid in the NON_AUTHENTICATED state.
+ * A welcome message precedes the execution of the test elements.
+ */
public class TestNonAuthenticated
extends SimpleFileProtocolTest
{
@@ -20,12 +24,19 @@
super( name );
}
+ /**
+ * Adds a welcome message to the {@link #preElements}.
+ * @throws Exception
+ */
public void setUp() throws Exception
{
super.setUp();
addTestFile( "Welcome.test", preElements );
}
+ /**
+ * Sets up tests valid in the non-authenticated state.
+ */
public static Test suite() throws Exception
{
TestSuite suite = new TestSuite();
1.3 +13 -0 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/TestSelected.java
Index: TestSelected.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/imapserver/TestSelected.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TestSelected.java 26 Nov 2002 14:53:48 -0000 1.2
+++ TestSelected.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -10,6 +10,10 @@
import junit.framework.Test;
import junit.framework.TestSuite;
+/**
+ * Runs tests for commands valid in the AUTHENTICATED state. A login session
+ * and SelectInbox session precedes the execution of the test elements.
+ */
public class TestSelected
extends TestAuthenticated
{
@@ -18,12 +22,21 @@
super( name );
}
+ /**
+ * Superclass sets up welcome message and login session in {@link #preElements}.
+ * A "SELECT INBOX" session is then added to these elements.
+ * @throws Exception
+ */
public void setUp() throws Exception
{
super.setUp();
addTestFile( "SelectInbox.test", preElements );
}
+ /**
+ * Provides all tests which should be run in the selected state. Each test name
+ * corresponds to a protocol session file.
+ */
public static Test suite() throws Exception
{
TestSuite suite = new TestSuite();
1.1 jakarta-james/proposals/imap2/test/org/apache/james/imapserver/ImapTest.java
Index: ImapTest.java
===================================================================
/*
* Copyright (C) The Apache Software Foundation. All rights reserved.
*
* This software is published under the terms of the Apache Software License
* version 1.1, a copy of which has been included with this distribution in
* the LICENSE file.
*/
package org.apache.james.imapserver;
/**
* Some constants to use when running Imap tests.
*/
public interface ImapTest
{
int PORT = 143;
String HOST = "localhost";
String USER = "imapuser";
String PASSWORD = "password";
String FROM_ADDRESS = "sender@localhost";
String TO_ADDRESS = USER + "@" + HOST;
int TIMEOUT = 30000;
}
1.2 +4 -0 jakarta-james/proposals/imap2/test/org/apache/james/remotemanager/InitialImapUsersTest.java
Index: InitialImapUsersTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/remotemanager/InitialImapUsersTest.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- InitialImapUsersTest.java 26 Nov 2002 14:53:48 -0000 1.1
+++ InitialImapUsersTest.java 27 Nov 2002 01:59:22 -0000 1.2
@@ -10,6 +10,10 @@
import junit.framework.Test;
import junit.framework.TestSuite;
+/**
+ * A test which uses the remote manager to set up a single user "imapuser"
+ * which is required for most Imap tests.
+ */
public final class InitialImapUsersTest
extends TestRemoteManager
{
1.3 +1 -1 jakarta-james/proposals/imap2/test/org/apache/james/remotemanager/UserManagementTest.java
Index: UserManagementTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/remotemanager/UserManagementTest.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- UserManagementTest.java 26 Nov 2002 14:53:48 -0000 1.2
+++ UserManagementTest.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -57,7 +57,7 @@
protected void deleteUser( String userName ) throws Exception
{
testElements.CL( "deluser " + userName );
- testElements.SL( "User " + userName + " deleted" );
+ testElements.SL( "User " + userName + " deleted", "UserManagementTest.java:60" );
runSessions();
}
}
1.3 +35 -25 jakarta-james/proposals/imap2/test/org/apache/james/test/AbstractProtocolTest.java
Index: AbstractProtocolTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/test/AbstractProtocolTest.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- AbstractProtocolTest.java 26 Nov 2002 14:53:48 -0000 1.2
+++ AbstractProtocolTest.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -1,6 +1,6 @@
package org.apache.james.test;
-import org.apache.james.imapserver.IMAPTest;
+import org.apache.james.imapserver.ImapTest;
import org.apache.james.imapserver.ImapHandler;
import org.apache.james.imapserver.ImapHost;
import org.apache.james.imapserver.ImapRequestHandler;
@@ -27,27 +27,34 @@
/**
* Abstract Protocol Test is the root of all of the James Imap Server test
- * cases. It provides functionality to create text files for matching
- * client requests and server responses. In order to use it however you
- * must create a sub class and set all the file names, etc up yourself.
- * All Comments are written by Andy Oliver who is still trying to figure out
- * some of it himself so don't take this as gospel
+ * cases. It provides basic functionality for running a protocol session
+ * as a JUnit test, and failing if exceptions are thrown.
+ * To create a test which reads the entire protocol session from a single
+ * protocol definition file, use the {@link SimpleFileProtocolTest}.
*
- * @author Unattributed Original Authors
+ * @author Darrell DeBoer
* @author Andrew C. Oliver
*/
public abstract class AbstractProtocolTest
- extends TestCase implements IMAPTest
+ extends TestCase implements ImapTest
{
+ /** The Protocol session which is run before the testElements */
protected ProtocolSession preElements = new ProtocolSession();
- protected ProtocolSession testElements;
+ /** The Protocol session which contains the tests elements */
+ protected ProtocolSession testElements = new ProtocolSession();
+ /** The Protocol session which is run after the testElements. */
protected ProtocolSession postElements = new ProtocolSession();
+ /** The host name to connect to for socket-based testing. */
protected String host = HOST;
+ /** The host port to connect to for socket-based testing. */
protected int port = PORT;
+ /** The timeout to set on the socket for socket-based testing. */
protected int timeout = TIMEOUT;
+ /** A UsersRepository which all tests share. */
private static UsersRepository users;
+ /** An ImapHost instance which all tests share. */
private static ImapHost imapHost;
public AbstractProtocolTest( String s )
@@ -55,14 +62,6 @@
super( s );
}
- // comment in TestCase
- public void setUp() throws Exception
- {
- super.setUp();
- testElements = new ProtocolSession();
-
- }
-
/**
* Uses a system property to determine whether to run tests locally, or against
* a remote server.
@@ -93,11 +92,11 @@
PrintWriter out = new PrintWriter( socket.getOutputStream(), true );
BufferedReader in = new BufferedReader( new InputStreamReader( socket.getInputStream() ) );
try {
- preElements.runSession( in, out );
- testElements.runSession( in, out );
- postElements.runSession( in, out );
+ preElements.runLiveSession( out, in );
+ testElements.runLiveSession( out, in );
+ postElements.runLiveSession( out, in );
}
- catch ( InvalidServerResponseException e ) {
+ catch ( ProtocolSession.InvalidServerResponseException e ) {
fail( e.getMessage() );
}
@@ -146,12 +145,15 @@
testElements.testResponse( serverIn );
postElements.testResponse( serverIn );
}
- catch ( InvalidServerResponseException e ) {
+ catch ( ProtocolSession.InvalidServerResponseException e ) {
fail( e.getMessage() );
}
}
- // TODO setup the session properly.
+ /**
+ * Provides an ImapSession to use for this test. An ImapSession is accosiated
+ * with a single client connection.
+ */
private ImapSession getImapSession() throws MailboxException
{
setUpEnvironment();
@@ -159,10 +161,14 @@
return session;
}
+ /**
+ * Initialises the UsersRepository and ImapHost on first call.
+ * TODO enable logging, set up components properly.
+ */
private void setUpEnvironment() throws MailboxException
{
if ( users == null || imapHost == null ) {
- users = new DummyUsersRepository();
+ users = new InMemoryUsersRepository();
DefaultUser user = new DefaultUser( USER, "SHA" );
user.setPassword( PASSWORD );
users.addUser( user );
@@ -172,7 +178,11 @@
}
}
- private class DummyUsersRepository extends AbstractUsersRepository
+ /**
+ * A simple, dummy implementation of UsersRepository to use for testing,
+ * which stored all users in memory.
+ */
+ private class InMemoryUsersRepository extends AbstractUsersRepository
{
private Map users = new HashMap();
1.2 +20 -1 jakarta-james/proposals/imap2/test/org/apache/james/test/FileProtocolSessionBuilder.java
Index: FileProtocolSessionBuilder.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/test/FileProtocolSessionBuilder.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- FileProtocolSessionBuilder.java 26 Nov 2002 14:53:48 -0000 1.1
+++ FileProtocolSessionBuilder.java 27 Nov 2002 01:59:22 -0000 1.2
@@ -14,6 +14,7 @@
import java.util.List;
/**
+ * A builder which generates a ProtocolSession from a test file.
*
* @author Darrell DeBoer <da...@apache.org>
*
@@ -27,6 +28,12 @@
private static final String CLOSE_UNORDERED_BLOCK_TAG = "}";
private static final String COMMENT_TAG = "#";
+ /**
+ * Builds a ProtocolSession by reading lines from the test file
+ * with the supplied name.
+ * @param fileName The name of the protocol session file.
+ * @return The ProtocolSession
+ */
public ProtocolSession buildProtocolSession( String fileName )
throws Exception
{
@@ -35,6 +42,11 @@
return session;
}
+ /**
+ * Adds all protocol elements from a test file to the ProtocolSession supplied.
+ * @param fileName The name of the protocol session file.
+ * @param session The ProtocolSession to add the elements to.
+ */
public void addTestFile( String fileName, ProtocolSession session )
throws Exception
{
@@ -47,6 +59,13 @@
addProtocolLinesFromStream( is, session, fileName );
}
+ /**
+ * Reads ProtocolElements from the supplied InputStream and adds
+ * them to the ProtocolSession.
+ * @param is The input stream containing the protocol definition.
+ * @param session The ProtocolSession to add elements to.
+ * @param fileName The name of the source file, for error messages.
+ */
public void addProtocolLinesFromStream( InputStream is,
ProtocolSession session,
String fileName )
1.2 +120 -45 jakarta-james/proposals/imap2/test/org/apache/james/test/ProtocolSession.java
Index: ProtocolSession.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/test/ProtocolSession.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ProtocolSession.java 26 Nov 2002 14:53:49 -0000 1.1
+++ ProtocolSession.java 27 Nov 2002 01:59:22 -0000 1.2
@@ -10,8 +10,8 @@
import org.apache.oro.text.perl.Perl5Util;
import java.io.BufferedReader;
-import java.io.InterruptedIOException;
import java.io.PrintWriter;
+import java.io.IOException;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
@@ -19,21 +19,26 @@
/**
* A protocol session which can be run against a reader and writer, which checks
* the server response against the expected values.
- * TODO extract the FileProtocolSession from this generic one, so we can build
- * protocol sessions from files with different formats.
* @author Darrell DeBoer <da...@apache.org>
*
* @version $Revision$
*/
public class ProtocolSession
{
- protected List _testElements = new ArrayList();
+ protected List testElements = new ArrayList();
private static final Perl5Util perl = new Perl5Util();
- // comment in TestCase
- public void runSession( BufferedReader in, PrintWriter out ) throws Exception
+ /**
+ * Executes the ProtocolSession in real time against the reader and writer
+ * supplied, writing client requests and reading server responses in the order
+ * that they appear in the test elements.
+ * If an exception occurs, no more test elements are executed.
+ * @param out The client requests are written to here.
+ * @param in The server responses are read from here.
+ */
+ public void runLiveSession( PrintWriter out, BufferedReader in ) throws Exception
{
- for ( Iterator iter = _testElements.iterator(); iter.hasNext(); ) {
+ for ( Iterator iter = testElements.iterator(); iter.hasNext(); ) {
Object obj = iter.next();
if ( obj instanceof ProtocolElement ) {
ProtocolElement test = ( ProtocolElement ) obj;
@@ -44,12 +49,13 @@
/**
* Write an entire client session to the specified PrintWriter. Server
- * responses are ignored, but may be collected for later testing with
- * {@link #testResponse}.
+ * responses are not collected, but clients may collect themfor later
+ * testing with {@link #testResponse}.
+ * @param out The client requests are written to here.
*/
public void writeClient( PrintWriter out ) throws Exception
{
- Iterator iterator = _testElements.iterator();
+ Iterator iterator = testElements.iterator();
while ( iterator.hasNext() ) {
ProtocolElement element = (ProtocolElement) iterator.next();
if ( element instanceof ClientRequest ) {
@@ -58,9 +64,16 @@
}
}
+ /**
+ * Reads Server responses from the supplied Buffered reader, ensuring that
+ * they match the expected responses for the protocol session. This permits
+ * clients to run a session asynchronously, by first writing the client requests
+ * with {@link #writeClient} and later testing the responses.
+ * @param in The server responses are read from here.
+ */
public void testResponse( BufferedReader in ) throws Exception
{
- Iterator iterator = _testElements.iterator();
+ Iterator iterator = testElements.iterator();
while ( iterator.hasNext() ) {
ProtocolElement element = (ProtocolElement) iterator.next();
if ( element instanceof ServerResponse ) {
@@ -74,23 +87,15 @@
*/
public void CL( String clientLine )
{
- _testElements.add( new ClientRequest( clientLine ) );
+ testElements.add( new ClientRequest( clientLine ) );
}
/**
- * adds a new Server Response line to the test elements
+ * adds a new Server Response line to the test elements, with the specified location.
*/
public void SL( String serverLine, String location )
{
- _testElements.add( new ServerResponse( serverLine, location ) );
- }
-
- /**
- * adds a new Server Response line to the test elements
- */
- public void SL( String serverLine )
- {
- _testElements.add( new ServerResponse( serverLine, "Location unknown.") );
+ testElements.add( new ServerResponse( serverLine, location ) );
}
/**
@@ -98,7 +103,7 @@
*/
public void SUB( List serverLines, String location )
{
- _testElements.add( new UnorderedBlockResponse( serverLines, location ) );
+ testElements.add( new ServerUnorderedBlockResponse( serverLines, location ) );
}
/**
@@ -106,48 +111,65 @@
*/
public void addProtocolElement( ProtocolElement element )
{
- _testElements.add( element );
+ testElements.add( element );
}
/**
- * This Line is sent to the server (everything after "CL: ") in expectation
- * that the server will respond.
+ * A client request, which write the specified message to a Writer.
*/
private class ClientRequest implements ProtocolElement
{
- private String _msg;
+ private String message;
- public ClientRequest( String msg )
+ /**
+ * Initialises the ClientRequest with the supplied message.
+ */
+ public ClientRequest( String message )
{
- _msg = msg;
+ this.message = message;
}
/**
- * Sends the request to the server
+ * Writes the request message to the PrintWriter.
*/
- public void testProtocol( PrintWriter out, BufferedReader in ) throws Exception
+ public void testProtocol( PrintWriter out, BufferedReader in )
{
- out.println( _msg );
+ out.println( message );
}
}
+ /**
+ * Represents a single-line server response, which reads a line
+ * from a reader, and compares it with the defined regular expression
+ * definition of this line.
+ */
private class ServerResponse implements ProtocolElement
{
private String expectedLine;
protected String location;
+ /**
+ * Sets up a server response.
+ * @param expectedPattern A Perl regular expression pattern used to test
+ * the line recieved.
+ * @param location A descriptive value to use in error messages.
+ */
public ServerResponse( String expectedPattern, String location )
{
this.expectedLine = expectedPattern;
this.location = location;
}
- public ServerResponse( String expectedPattern )
- {
- this( expectedPattern, "" );
- }
-
- public void testProtocol( PrintWriter out, BufferedReader in ) throws Exception
+ /**
+ * Reads a line from the supplied reader, and tests that it matches
+ * the expected regular expression.
+ * @param out Is ignored.
+ * @param in The server response is read from here.
+ * @throws InvalidServerResponseException If the actual server response didn't
+ * match the regular expression expected.
+ */
+ public void testProtocol( PrintWriter out, BufferedReader in )
+ throws InvalidServerResponseException
{
String testLine = readLine( in );
if ( ! match( expectedLine, testLine ) ) {
@@ -158,6 +180,13 @@
}
}
+ /**
+ * A convenience method which returns true if the actual string
+ * matches the expected regular expression.
+ * @param expected The regular expression used for matching.
+ * @param actual The actual message to match.
+ * @return <code>true</code> if the actual matches the expected.
+ */
protected boolean match( String expected, String actual )
{
String pattern = "m/" + expected + "/";
@@ -170,12 +199,13 @@
* @param in BufferedReader for getting the server response
* @return String of the line from the server
*/
- protected String readLine( BufferedReader in ) throws Exception
+ protected String readLine( BufferedReader in )
+ throws InvalidServerResponseException
{
try {
return in.readLine();
}
- catch ( InterruptedIOException e ) {
+ catch ( IOException e ) {
String errMsg = "\nLocation: " + location +
"\nExpected: " + expectedLine +
"\nReason: Server Timeout.";
@@ -184,18 +214,37 @@
}
}
- private class UnorderedBlockResponse extends ServerResponse
+ /**
+ * Represents a set of lines which must be recieved from the server,
+ * in a non-specified order.
+ */
+ private class ServerUnorderedBlockResponse extends ServerResponse
{
private List expectedLines = new ArrayList();
- public UnorderedBlockResponse( List expectedLines, String location )
+ /**
+ * Sets up a ServerUnorderedBlockResponse with the list of expected lines.
+ * @param expectedLines A list containing a reqular expression for each
+ * expected line.
+ * @param location A descriptive location string for error messages.
+ */
+ public ServerUnorderedBlockResponse( List expectedLines, String location )
{
super( "<Unordered Block>", location );
this.expectedLines = expectedLines;
}
+ /**
+ * Reads lines from the server response and matches them against the
+ * list of expected regular expressions. Each regular expression in the
+ * expected list must be matched by only one server response line.
+ * @param out Is ignored.
+ * @param in Server responses are read from here.
+ * @throws InvalidServerResponseException If a line is encountered which doesn't
+ * match one of the expected lines.
+ */
public void testProtocol( PrintWriter out, BufferedReader in )
- throws Exception
+ throws InvalidServerResponseException
{
List testLines = new ArrayList( expectedLines );
while ( testLines.size() > 0 )
@@ -234,8 +283,34 @@
}
}
+ /**
+ * Represents a generic protocol element, which may write requests to the server,
+ * read responses from the server, or both. Implementations should test the server
+ * response against an expected response, and throw an exception on mismatch.
+ */
interface ProtocolElement
{
- void testProtocol( PrintWriter out, BufferedReader in ) throws Exception;
+ /**
+ * Executes the ProtocolElement against the supplied read and writer.
+ * @param out Client requests are written to here.
+ * @param in Server responses are read from here.
+ * @throws InvalidServerResponseException If the actual server response
+ * doesn't match the one expected.
+ */
+ void testProtocol( PrintWriter out, BufferedReader in )
+ throws InvalidServerResponseException;
+ }
+
+ /**
+ * An exception which is thrown when the actual response from a server
+ * is different from that expected.
+ */
+ public class InvalidServerResponseException extends Exception
+ {
+ public InvalidServerResponseException( String message )
+ {
+ super( message );
+ }
}
+
}
1.3 +19 -0 jakarta-james/proposals/imap2/test/org/apache/james/test/SimpleFileProtocolTest.java
Index: SimpleFileProtocolTest.java
===================================================================
RCS file: /home/cvs/jakarta-james/proposals/imap2/test/org/apache/james/test/SimpleFileProtocolTest.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SimpleFileProtocolTest.java 26 Nov 2002 14:53:49 -0000 1.2
+++ SimpleFileProtocolTest.java 27 Nov 2002 01:59:22 -0000 1.3
@@ -6,6 +6,8 @@
* A Protocol test which reads the test protocol session from a file. The
* file read is taken as "<test-name>.test", where <test-name> is the value
* passed into the constructor.
+ * Subclasses of this test can set up {@link #preElements} and {@link #postElements}
+ * for extra elements not defined in the protocol session file.
*/
public class SimpleFileProtocolTest
extends AbstractProtocolTest
@@ -13,11 +15,21 @@
private FileProtocolSessionBuilder builder =
new FileProtocolSessionBuilder();
+ /**
+ * Sets up a SimpleFileProtocolTest which reads the protocol session from
+ * a file of name "<fileName>.test". This file should be available in the classloader
+ * in the same location as this test class.
+ * @param fileName The name of the file to read protocol elements from.
+ */
public SimpleFileProtocolTest( String fileName )
{
super( fileName );
}
+ /**
+ * Reads test elements from the protocol session file and adds them to the
+ * {@link #testElements} ProtocolSession. Then calls {@link #runSessions}.
+ */
protected void runTest() throws Throwable
{
String fileName = getName() + ".test";
@@ -26,6 +38,13 @@
runSessions();
}
+ /**
+ * Finds the protocol session file identified by the test name, and builds
+ * protocol elements from it. All elements from the definition file are added
+ * to the supplied ProtocolSession.
+ * @param fileName The name of the file to read
+ * @param session The ProtocolSession to add elements to.
+ */
protected void addTestFile( String fileName, ProtocolSession session) throws Exception
{
// Need to find local resource.
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>