/*
 *                 Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 *
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
 * Microsystems, Inc. All Rights Reserved.
 */


package org.netbeans.modules.j2ee.server.web;

import java.io.IOException;
import java.io.InputStream;
import java.io.File;
import java.util.EventListener;
import java.util.EventObject;
import javax.swing.event.EventListenerList;

/** Interface which provides access to the JSP compiler of a server instance.
 * There are two basic purposes of this interface:
 * <ul>
 *  <li>To allow accessing the servlets generated from JSPs by the running 
 *   server, and associated information, such as mapping between servlet and 
 *   JSP lines.</li>
 *  <li>To provide compilation functionality usable from the IDE without
 *   requiring to connect to a running server instance. This part is optional, 
 *   the server integration module may choose to implement it or not.</li>
 * </ul>
 */
public abstract class FfjJspCompileContext {
    
    private EventListenerList listeners;

    /** Creates a servlet <-> JSP mapping for a given JSP. May be null if the server is not running
     *  or the page has not been compiled. Also may be null if the server plugin does not support 
     *  creation of the line mapping information.
     * @param wmRoot root of the web module (document base) 
     * @param jspPage the page for which the mapping should be created
     * @exception IOException if the creation of the mapping did not succeed
     * @return the source mapper, or null
     */
    public abstract JspSourceMapper createSourceMapper(File wmRoot, File jspPage) throws IOException;
    
    /** Returns support for viewing the generated servlet. 
     * May return null if the server does not support viewing the generated servlet 
     * (e.g. it is remote), or if it is not running.
     * @param wmRoot root of the web module (document base) 
     * @param jspPage the page for which the support should be returned
     * @return the support, or null
     */
    public abstract ViewServletSupport getViewServletSupport(File wmRoot, File jspPage);
    
    
    /** Returns support for compiling the page into a <code>.class</code> file.
     * May return null if the server/plugin does not support compiling the JSP inside the IDE.
     * If this method returns a non-null value, then the <code>getViewServletSupport(...)</code>
     * must also return non-null.
     * @param wmRoot root of the web module (document base) 
     * @param jspPage the page for which the support should be returned
     * @return the support, or null
     */
    public abstract CompilationSupport getCompilationSupport(File wmRoot, File jspPage);
    
    /** Adds a listener on compilation events. */
    public final synchronized void addCompilationEventListener(CompilationEventListener listener) {
        if (listeners == null) {
            listeners = new EventListenerList();
        }
        listeners.add(CompilationEventListener.class, listener);
    }

    /** Removes a listener on compilation events. */
    public final synchronized void removeCompilationEventListener(CompilationEventListener listener) {
        if (listeners != null) {
            listeners.remove(CompilationEventListener.class, listener);
        }
    }
    
    /** Fires a CompilationEvent to all registered listeners. */
    protected final void fireCompilationEvent(CompilationEvent event) {
        if (listeners != null) {
             Object[] listenerArray = listeners.getListenerList();
             // Process the listeners last to first, notifying
             // those that are interested in this event
             for (int i = listenerArray.length-2; i>=0; i-=2) {
                 if (listenerArray[i]==CompilationEventListener.class) {
                     ((CompilationEventListener)listenerArray[i+1]).compilationChange(event);
                 }
             }
        }
    }

    /** Allows getting the generated servlet for a given page. */
    public interface ViewServletSupport {
        
        /** Returns the current servlet file. May return null if the page is not compiled.
         * The IDE may call the <code>lastModified()</code> method on the file 
         * to determine whether the servlet must be reloaded.
         */
        public File getCurrentServletFile();
        
        /** Returns the actual class name of the servlet. May return null if the page is not compiled.
         * Note that in theory this should be deducible from the servlet file name and the root of the
         * temporary directory, however in practice the servlet may not obey the Java conventions for
         * class naming.
         */
        public String getRealClassName();
        
        /** Returns the root of the temporary directory corresponding 
         * to the web module root.
         */
        public File getWMTempRoot();
        
        /** Returns encoding of the servlet generated by the JSP compiler for a
         * given page. The returned encoding is used to open the servlet in the editor.
         */
        public String getServletEncoding();
        
    } // end of ViewServletSupport
    
    /** Allows compiling a given page inside the IDE. */
    public interface CompilationSupport {
        
        /** Returns whether the JSP page in newer than the servlet or the class file.
         */
        public boolean isOutDated();
        
        /** Compiles a JSP into a servlet.
         * Returns error messages encountered during compilation, or an empty array
         * if there were no errors.
         */
        public ErrorDescriptor[] compileJspToServlet(boolean isErrorPage, 
            String compilationURI, ClassLoader cl) throws IOException;
        
        /** Cleans the compiled files associated with this page (for compilation embedded in the IDE).
         */
        public void clean() throws IOException;
        
    } // end of CompilationSupport

    /** Event that describes the state change on the server pertinent to 
     * a particular resource (JSP)
     **/
    public static abstract class CompilationEvent extends EventObject {
        
        public static final int SERVLET_DELETED             = 1;
        public static final int PAGE_RECOMPILED_OK          = 2;
        public static final int PAGE_RECOMPILED_WITH_ERRORS = 3;

        /** Constructs a new CompilationEvent. */
        public CompilationEvent(Object source) {
            super(source);
        }
        
        /** Returns the document base of the web module to which the 
         * event applies. */
        public abstract File getWebModule();
        
        /** Returns the resource (JSP) to which the event applies. */
        public abstract File getResource();
        
        /** Returns the type of the event - one of the constants defined above. */
        public abstract int getEventType();
        
        /** Returns an array containing compilation errors, in case that 
         * the compilation failed. In other cases, returns null. */
        public abstract ErrorDescriptor[] getErrors();
        
    } // end of CompilationEvent
    
    
    /** EventListener for compilation events. 
     **/
    public interface CompilationEventListener extends EventListener {
        
        /** Notifies the listener of a compilation-related change. */
        public void compilationChange(CompilationEvent event);
        
    } // end of CompilationEventListener

    /** Interface which describes an error message encountered during compilation. */
    public static class ErrorDescriptor {

        protected File webModule;
        protected File resource;
        protected int line;
        protected int column;
        protected String errorMessage;
        protected String referenceText;

        public ErrorDescriptor(File webModule, File resource, int line, 
        int column, String errorMessage, String referenceText) {
            this.webModule = webModule;
            this.resource = resource;
            this.line = line;
            this.column = column;
            this.errorMessage = errorMessage;
            this.referenceText = referenceText;
        }

        /** Returns a file containing the error.
         */
        public File getWebModule() {
            return webModule;
        }

        /** Returns a file containing the error. 
         * This may be different from the resource for which compilation was 
         * requested, as the error may be in a fragment.
         */
        public File getResource() {
            return resource;
        }

        /** Get the line of the error. */
        public int getLine() {
            return line;
        }

        /** Get the column of the error. */
        public int getColumn() {
            return column;
        }

        /** Get the error message associated with the error. */
        public String getErrorMessage() {
            return errorMessage;
        }

        /** Get the string which contains the error (i.e. contents of the line containing the error. */
        public String getReferenceText() {
            return referenceText;
        }

    } // end of ErrorDescriptor

}