/*
 *   Copyright 2012 Brian Rosenberger (Brutex Network)
 *
 *   Licensed 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.
 */
package net.brutex.xservices.ws;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlElement;

import net.brutex.xservices.types.HostConnection;
import net.brutex.xservices.types.MailMimeType;
import net.brutex.xservices.types.ReturnCode;
import net.brutex.xservices.types.ant.FileSetResource;
import net.brutex.xservices.util.BrutexNamespaces;

import org.apache.cxf.annotations.WSDLDocumentation;

/**
 * Bundles various method for sending and receiving mails
 *
 * @author Brian Rosenberger, bru@brutex.de
 * @since 2.0.0
 */
@WebService(targetNamespace = BrutexNamespaces.WS_XSERVICES)
@WSDLDocumentation("Various mail service operations.")
public interface MailService {

    final String PARAM_SMTPHOST = "mailhost";
    final String PARAM_SENDER = "from";
    final String PARAM_RECEIVER = "to";
    final String PARAM_SUBJECT = "subject";
    final String PARAM_MESSAGE = "message";
    final String PARAM_ATTACHMENTS = "attachments";
    
    /**
     * Simple mail send operation with sender, single receiver, subject and message.
     * 
     * @param mailhost	connection details for the SMTP server to use
     * @param from		mail address to be used as sender
     * @param tolist	mail address of the receiver
     * @param subject	subject of the mail
     * @param message	mail body
     * @return ReturnCode
     */
    @WebMethod(operationName = "sendMailSimple")
    @WSDLDocumentation(value = "Send an email (simple).")
    public ReturnCode sendMailSimple(
    		@WebParam(name = PARAM_SMTPHOST) @XmlElement(required=true, nillable=false) HostConnection mailhost,
            @WebParam(name = PARAM_SENDER) @XmlElement(required=true) String from,
            @WebParam(name = PARAM_RECEIVER) @XmlElement(required=true, nillable=false) String tolist,
            @WebParam(name = PARAM_SUBJECT) String subject,
            @WebParam(name = PARAM_MESSAGE) String message);

    /**
     * Simple mail send operation with sender, single receiver, subject and message
     * including support for file attachments.
     *
     * @param mailhost	connection details for the SMTP server to use
     * @param from		mail address to be used as sender
     * @param tolist	mail address of the receiver
     * @param subject	subject of the mail
     * @param message	mail body
     * @param res		attachments
     * @return ReturnCode
     */
    @WebMethod(operationName = "sendMailSimpleWithAttachment")
    @WSDLDocumentation(value = "Send an email with attachment (simple).")
    public ReturnCode sendMailSimpleWithAttachment(
    		@WebParam(name = PARAM_SMTPHOST) @XmlElement(required=true, nillable=false) HostConnection mailhost,
            @WebParam(name = PARAM_SENDER) @XmlElement(required=true, nillable=false) String from,
            @WebParam(name = PARAM_RECEIVER) @XmlElement(required=true, nillable=false) String tolist,
            @WebParam(name = PARAM_SUBJECT) String subject,
            @WebParam(name = PARAM_MESSAGE) String message,
            @WebParam(name = PARAM_ATTACHMENTS) FileSetResource res);

    /**
     * Send email with a lot of options
     *
     * @param mailhost	connection details for the SMTP server to use
     * @param from		mail address to be used as sender
     * @param tolist	mail address of the receiver
     * @param cclist	mail carbon copy receiver
     * @param bcclist	mail blind carbon copy receiver
     * @param subject	subject of the mail
     * @param mimetype	message MIME type (i.e. text/plain)
     * @param charset	character set to use (i.e. utf-8, iso-8859-15)
     * @param message	mail body
     * @param res		attachments
     * @param ssl		use SSL
     * @param tls		use TLS
     * @return ReturnCode
     */
    @WebMethod(operationName = "sendMail")
    @WSDLDocumentation(value = "Send an email (advanced).")
    public ReturnCode sendMail(
    		@WebParam(name = PARAM_SMTPHOST) @XmlElement(required=true, nillable=false) HostConnection mailhost,
            @WebParam(name = PARAM_SENDER) @XmlElement(required=true, nillable=false) String from,
            @WebParam(name = PARAM_RECEIVER) @XmlElement(required=true, nillable=false) String tolist,
            @WebParam(name = "cc") String cclist,
            @WebParam(name = "bcc") String bcclist,
            @WebParam(name = PARAM_SUBJECT) String subject,
            @WebParam(name = "mimetype") MailMimeType mimetype,
            @WebParam(name = "charset") String charset,
            @WebParam(name = PARAM_MESSAGE) String message,
            @WebParam(name = PARAM_ATTACHMENTS) FileSetResource res,
            @WebParam(name = "useSSL") boolean ssl,
            @WebParam(name = "useStartTLS") boolean tls);

 
}