Author: tchemit Date: 2009-09-20 19:11:28 +0200 (Sun, 20 Sep 2009) New Revision: 579 Modified: trunk/src/main/java/org/nuiton/io/rest/DefaultRestClientConfiguration.java trunk/src/main/java/org/nuiton/io/rest/RestClient.java trunk/src/main/java/org/nuiton/io/rest/RestClientConfiguration.java trunk/src/main/java/org/nuiton/io/rest/RestDataNotFoundException.java trunk/src/main/java/org/nuiton/io/rest/RestException.java trunk/src/main/java/org/nuiton/io/rest/RestRequest.java trunk/src/main/java/org/nuiton/io/rest/RestRequestBuilder.java trunk/src/main/java/org/nuiton/io/rest/RestSession.java trunk/src/main/java/org/nuiton/mail/MailSender.java trunk/src/main/java/org/nuiton/mail/ProjectJavamailMailSender.java Log: add javadoc on new code + improve RestClient api Modified: trunk/src/main/java/org/nuiton/io/rest/DefaultRestClientConfiguration.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/DefaultRestClientConfiguration.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/DefaultRestClientConfiguration.java 2009-09-20 17:11:28 UTC (rev 579) @@ -5,8 +5,10 @@ import org.apache.commons.lang.builder.ToStringStyle; /** - * + * Default implementation of a {@link RestClientConfiguration}. + * * @author chemit + * @since 1.0.3 */ public class DefaultRestClientConfiguration implements RestClientConfiguration { Modified: trunk/src/main/java/org/nuiton/io/rest/RestClient.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestClient.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestClient.java 2009-09-20 17:11:28 UTC (rev 579) @@ -8,25 +8,72 @@ import org.apache.commons.logging.LogFactory; /** - * + * Abtract REST client. + * * @author chemit + * @since 1.0.3 */ public abstract class RestClient { private static final Log log = LogFactory.getLog(RestClient.class); - protected final RestClientConfiguration configuration; + /** + * rest client configuration + */ + protected RestClientConfiguration configuration; + /** + * rest session + */ protected RestSession session; - protected Map<String, RestRequestBuilder> requestBuilders; + /** + * registred requests + */ + protected final Map<String, RestRequestBuilder> requestBuilders; + /** + * Add the default available requests for this client. + * + * <b>Note:</b> This method is invoked in the constructor of the client. + * + */ + protected abstract void addDefaultRequests(); + + /** + * Open the client. + * + * <b>Note:</b> At the end of this method, if every thing is ok, then + * the method {@link #isOpen()} must returns {@code true}. + * + * @param session the rest session + * @throws IOException if any pb + */ protected abstract void open(RestSession session) throws IOException; + /** + * Close the client. + * + * <b>Note:</b> At the end of this method, if every thing is ok, then + * the method {@link #isOpen()} must returns {@code false}. + * + * @param session the rest session + * @throws IOException if any pb + */ protected abstract void close(RestSession session) throws IOException; + public RestClient() { + this.requestBuilders = new TreeMap<String, RestRequestBuilder>(); + addDefaultRequests(); + } + public RestClient(RestClientConfiguration configuration) { + this(); this.configuration = configuration; - this.requestBuilders = new TreeMap<String, RestRequestBuilder>(); } + /** + * Add a request into the client. + * + * @param builder the new request to add + */ public void addRequestBuilder(RestRequestBuilder builder) { String name = builder.getName(); if (requestBuilders.containsKey(name)) { @@ -35,6 +82,13 @@ requestBuilders.put(name, builder); } + /** + * Obtain a request given his id and the args given. + * + * @param id id of the request + * @param args args passed to build the request + * @return the new request + */ public RestRequest getRequest(String id, Object... args) { RestRequestBuilder builder = requestBuilders.get(id); if (builder == null) { @@ -45,6 +99,13 @@ return r; } + /** + * Ask some data from the server + * + * @param request request used for asking data + * @return the stream of the response + * @throws RestException + */ public InputStream askData(RestRequest request) throws RestException { if (!isOpen()) { throw new IllegalStateException("the client is not opened"); @@ -58,6 +119,13 @@ } } + /** + * Send some datas to the server. + * + * @param request the request used for sending data + * @return the stream of the response + * @throws RestException + */ public InputStream sendData(RestRequest request) throws RestException { if (!isOpen()) { throw new IllegalStateException("the client is not opened"); @@ -71,6 +139,14 @@ } } + /** + * Open the client. + * + * <b>Note:</b> this method will instanciate the {@link #session} and invoke + * the method {@link #open(org.nuiton.io.rest.RestSession)}. + * + * @throws RestException + */ public void open() throws RestException { if (isOpen()) { @@ -100,6 +176,14 @@ } } + /** + * Close the client. + * + * <b>Note:</b> this method will erase the {@link #session} and invoke + * the method {@link #close(org.nuiton.io.rest.RestSession)}. + * + * @throws RestException + */ public void close() throws RestException { if (!isOpen()) { return; @@ -114,15 +198,40 @@ } } + /** + * Is the client opened ? + * + * @return {@code true} if the internal {@link #session} is opened, + * {@code false} otherwise. + */ public boolean isOpen() { return session != null; } + /** + * + * @return the internal rest {@link #session} + */ public RestSession getSession() { return session; } + /** + * + * @return the internal {@link #configuration} + */ public RestClientConfiguration getConfiguration() { return configuration; } + + /** + * Use a new configuration. + * + * TODO : this method should check client is not opened! + * + * @param configuration the new configuration + */ + public void setConfiguration(RestClientConfiguration configuration) { + this.configuration = configuration; + } } Modified: trunk/src/main/java/org/nuiton/io/rest/RestClientConfiguration.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestClientConfiguration.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestClientConfiguration.java 2009-09-20 17:11:28 UTC (rev 579) @@ -3,8 +3,10 @@ import java.net.URL; /** - * + * Contract of a {@link RestClient}. + * * @author chemit + * @since 1.0.3 */ public interface RestClientConfiguration { Modified: trunk/src/main/java/org/nuiton/io/rest/RestDataNotFoundException.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestDataNotFoundException.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestDataNotFoundException.java 2009-09-20 17:11:28 UTC (rev 579) @@ -1,12 +1,11 @@ -/* - * To change this template, choose Tools | Templates - * and open the template in the editor. - */ package org.nuiton.io.rest; /** - * + * Exception to be raised if a data does not exist ina 'askData' request, says + * when the rest server returns a {@code 4XX} status code. + * * @author chemit + * @since 1.0.3 */ public class RestDataNotFoundException extends RestException { Modified: trunk/src/main/java/org/nuiton/io/rest/RestException.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestException.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestException.java 2009-09-20 17:11:28 UTC (rev 579) @@ -4,7 +4,7 @@ * Base exception for any excpeiton in rest service. * * @author chemit - * @since 1.0.0 + * @since 1.0.3 */ public class RestException extends Exception { Modified: trunk/src/main/java/org/nuiton/io/rest/RestRequest.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestRequest.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestRequest.java 2009-09-20 17:11:28 UTC (rev 579) @@ -4,8 +4,10 @@ import java.util.Map; /** - * + * The contract of a rest request. + * * @author chemit + * @since 1.0.3 */ public interface RestRequest { Modified: trunk/src/main/java/org/nuiton/io/rest/RestRequestBuilder.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestRequestBuilder.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestRequestBuilder.java 2009-09-20 17:11:28 UTC (rev 579) @@ -1,8 +1,10 @@ package org.nuiton.io.rest; /** - * + * The contract of a request builder. + * * @author chemit + * @since 1.0.3 */ public interface RestRequestBuilder { Modified: trunk/src/main/java/org/nuiton/io/rest/RestSession.java =================================================================== --- trunk/src/main/java/org/nuiton/io/rest/RestSession.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/io/rest/RestSession.java 2009-09-20 17:11:28 UTC (rev 579) @@ -26,8 +26,10 @@ import org.apache.commons.logging.LogFactory; /** - * + * A REST session. + * * @author chemit + * @since 1.0.3 */ public class RestSession { Modified: trunk/src/main/java/org/nuiton/mail/MailSender.java =================================================================== --- trunk/src/main/java/org/nuiton/mail/MailSender.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/mail/MailSender.java 2009-09-20 17:11:28 UTC (rev 579) @@ -1,72 +1,46 @@ package org.nuiton.mail; -/* - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - /** - * Defines the sender of the announcement if the list of developer is empty or - * if the sender is not a member of the development team. + * Defines the sender of a email. * - * @author Stephane Nicoll + * Note : this code was stolen in {@code maven-changes-plugin}, should thanks + * them... + * + * @author chemit + * @since 1.0.3 */ -public class MailSender -{ +public class MailSender { private String name; - private String email; - - public MailSender() - { + public MailSender() { super(); } - - public MailSender( String name, String email ) - { + public MailSender(String name, String email) { this.name = name; this.email = email; } - public String getName() - { + public String getName() { return name; } - public void setName( String name ) - { + public void setName(String name) { this.name = name; } - public String getEmail() - { + public String getEmail() { return email; } - public void setEmail( String email ) - { + public void setEmail(String email) { this.email = email; } - public String toString() - { + @Override + public String toString() { return getName() + " (" + getEmail() + ")"; } } Modified: trunk/src/main/java/org/nuiton/mail/ProjectJavamailMailSender.java =================================================================== --- trunk/src/main/java/org/nuiton/mail/ProjectJavamailMailSender.java 2009-09-19 18:29:10 UTC (rev 578) +++ trunk/src/main/java/org/nuiton/mail/ProjectJavamailMailSender.java 2009-09-20 17:11:28 UTC (rev 579) @@ -1,24 +1,5 @@ package org.nuiton.mail; -/* - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ - import java.security.Security; import java.util.Date; import java.util.Iterator; @@ -41,69 +22,64 @@ /** * Helper class for sending email. + * + * Note : this code was stolen in {@code maven-changes-plugin}, should thanks + * them... + * + * @author chemit + * @since 1.0.3 */ public class ProjectJavamailMailSender - extends AbstractMailSender -{ - private static final String SSL_FACTORY = "javax.net.ssl.SSLSocketFactory"; + extends AbstractMailSender { + private static final String SSL_FACTORY = "javax.net.ssl.SSLSocketFactory"; // ---------------------------------------------------------------------- // // ---------------------------------------------------------------------- - private Properties userProperties; - private Properties props; // ---------------------------------------------------------------------- // Component Lifecycle // ---------------------------------------------------------------------- - - public void initialize() - { - if ( StringUtils.isEmpty( getSmtpHost() ) ) - { - System.out.println( "Error in configuration: Missing smtpHost." ); + public void initialize() { + if (StringUtils.isEmpty(getSmtpHost())) { + System.out.println("Error in configuration: Missing smtpHost."); } - if ( getSmtpPort() == 0 ) - { - setSmtpPort( DEFAULT_SMTP_PORT ); + if (getSmtpPort() == 0) { + setSmtpPort(DEFAULT_SMTP_PORT); } props = new Properties(); - props.put( "mail.smtp.host", getSmtpHost() ); + props.put("mail.smtp.host", getSmtpHost()); - props.put( "mail.smtp.port", String.valueOf( getSmtpPort() ) ); + props.put("mail.smtp.port", String.valueOf(getSmtpPort())); - if ( getUsername() != null ) - { - props.put( "mail.smtp.auth", "true" ); + if (getUsername() != null) { + props.put("mail.smtp.auth", "true"); } - props.put( "mail.debug", String.valueOf( getLogger().isDebugEnabled() ) ); + props.put("mail.debug", String.valueOf(getLogger().isDebugEnabled())); - if ( isSslMode() ) - { - Security.addProvider( new com.sun.net.ssl.internal.ssl.Provider() ); + if (isSslMode()) { + Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider()); - props.put( "mail.smtp.socketFactory.port", String.valueOf( getSmtpPort() ) ); + props.put("mail.smtp.socketFactory.port", String.valueOf(getSmtpPort())); - props.put( "mail.smtp.socketFactory.class", SSL_FACTORY ); + props.put("mail.smtp.socketFactory.class", SSL_FACTORY); - props.put( "mail.smtp.socketFactory.fallback", "false" ); + props.put("mail.smtp.socketFactory.fallback", "false"); } - if ( userProperties != null ) - { - for ( Iterator i = userProperties.keySet().iterator(); i.hasNext(); ) - { + if (userProperties != null) { + for (Iterator<?> i = userProperties.keySet().iterator(); i.hasNext();) { String key = (String) i.next(); - String value = userProperties.getProperty( key ); + String value = userProperties.getProperty(key); - props.put( key, value ); + props.put(key, value); } } } @@ -111,90 +87,76 @@ // ---------------------------------------------------------------------- // MailSender Implementation // ---------------------------------------------------------------------- + @Override + public void send(MailMessage mail) + throws MailSenderException { + verify(mail); - public void send( MailMessage mail ) - throws MailSenderException - { - verify( mail ); - - try - { + try { Authenticator auth = null; - if ( getUsername() != null ) - { - auth = new Authenticator() - { - protected PasswordAuthentication getPasswordAuthentication() - { - return new PasswordAuthentication( getUsername(), getPassword() ); + if (getUsername() != null) { + auth = new Authenticator() { + + @Override + protected PasswordAuthentication getPasswordAuthentication() { + return new PasswordAuthentication(getUsername(), getPassword()); } }; } - Session session = Session.getDefaultInstance( props, auth ); + Session session = Session.getDefaultInstance(props, auth); - session.setDebug( getLogger().isDebugEnabled() ); + session.setDebug(getLogger().isDebugEnabled()); - Message msg = new MimeMessage( session ); - InternetAddress addressFrom = new InternetAddress( mail.getFrom().getRfc2822Address() ); - msg.setFrom( addressFrom ); + Message msg = new MimeMessage(session); + InternetAddress addressFrom = new InternetAddress(mail.getFrom().getRfc2822Address()); + msg.setFrom(addressFrom); - if ( mail.getToAddresses().size() > 0 ) - { + if (mail.getToAddresses().size() > 0) { InternetAddress[] addressTo = new InternetAddress[mail.getToAddresses().size()]; int count = 0; - for ( Iterator i = mail.getToAddresses().iterator(); i.hasNext(); ) - { - String address = ( (MailMessage.Address) i.next() ).getRfc2822Address(); - addressTo[count++] = new InternetAddress( address ); + for (Iterator<?> i = mail.getToAddresses().iterator(); i.hasNext();) { + String address = ((MailMessage.Address) i.next()).getRfc2822Address(); + addressTo[count++] = new InternetAddress(address); } - msg.setRecipients( Message.RecipientType.TO, addressTo ); + msg.setRecipients(Message.RecipientType.TO, addressTo); } - if ( mail.getCcAddresses().size() > 0 ) - { + if (mail.getCcAddresses().size() > 0) { InternetAddress[] addressCc = new InternetAddress[mail.getCcAddresses().size()]; int count = 0; - for ( Iterator i = mail.getCcAddresses().iterator(); i.hasNext(); ) - { - String address = ( (MailMessage.Address) i.next() ).getRfc2822Address(); - addressCc[count++] = new InternetAddress( address ); + for (Iterator<?> i = mail.getCcAddresses().iterator(); i.hasNext();) { + String address = ((MailMessage.Address) i.next()).getRfc2822Address(); + addressCc[count++] = new InternetAddress(address); } - msg.setRecipients( Message.RecipientType.CC, addressCc ); + msg.setRecipients(Message.RecipientType.CC, addressCc); } - if ( mail.getBccAddresses().size() > 0 ) - { + if (mail.getBccAddresses().size() > 0) { InternetAddress[] addressBcc = new InternetAddress[mail.getBccAddresses().size()]; int count = 0; - for ( Iterator i = mail.getBccAddresses().iterator(); i.hasNext(); ) - { - String address = ( (MailMessage.Address) i.next() ).getRfc2822Address(); - addressBcc[count++] = new InternetAddress( address ); + for (Iterator<?> i = mail.getBccAddresses().iterator(); i.hasNext();) { + String address = ((MailMessage.Address) i.next()).getRfc2822Address(); + addressBcc[count++] = new InternetAddress(address); } - msg.setRecipients( Message.RecipientType.BCC, addressBcc ); + msg.setRecipients(Message.RecipientType.BCC, addressBcc); } // Setting the Subject and Content Type - msg.setSubject( mail.getSubject() ); - msg.setContent( mail.getContent(), mail.getContentType() == null ? "text/plain" : mail.getContentType() ); + msg.setSubject(mail.getSubject()); + msg.setContent(mail.getContent(), mail.getContentType() == null ? "text/plain" : mail.getContentType()); - if ( mail.getSendDate() != null ) - { - msg.setHeader( "Date", DateFormatUtils.getDateHeader( mail.getSendDate() ) ); + if (mail.getSendDate() != null) { + msg.setHeader("Date", DateFormatUtils.getDateHeader(mail.getSendDate())); + } else { + msg.setHeader("Date", DateFormatUtils.getDateHeader(new Date())); } - else - { - msg.setHeader( "Date", DateFormatUtils.getDateHeader( new Date() ) ); - } // Send the message - Transport.send( msg ); + Transport.send(msg); + } catch (MessagingException e) { + throw new MailSenderException("Error while sending mail.", e); } - catch ( MessagingException e ) - { - throw new MailSenderException( "Error while sending mail.", e ); - } } }