001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.modules.web.spi.webmodule;
043:
044: import java.io.File;
045: import java.util.Set;
046:
047: import org.netbeans.modules.web.api.webmodule.*;
048: import org.netbeans.modules.web.webmodule.WebModuleExtenderBridge;
049: import org.openide.filesystems.FileObject;
050: import org.openide.util.Parameters;
051:
052: /**
053: * Encapsulates a web framework.
054: *
055: * <p>This class allows providing support for web frameworks. It can be used
056: * to extend a web module with a web framework, to find out whether a web
057: * module is already extender by a web framework, or to retrieve a web framework's
058: * specific configuration files.</p>
059: *
060: * <p>Instances of this class are registered in the <code>j2ee/webtier/framework</code>
061: * in the module layer.</p>
062: *
063: * @author Petr Pisl, Andrei Badea
064: */
065: public abstract class WebFrameworkProvider {
066:
067: private final String name;
068: private final String description;
069:
070: /**
071: * Creates a new web framework with a name and description.
072: *
073: * @param name the short name of this web framework (e.g., "Struts"); never null.
074: * @param description the description of this web framework (e.g., "An open source framework based on the MVC pattern"); can be null.
075: * @throws NullPointerException if the <code>name</code> parameter is null.
076: */
077: public WebFrameworkProvider(String name, String description) {
078: Parameters.notNull("name", name); // NOI18N
079: this .name = name;
080: this .description = description;
081: }
082:
083: /**
084: * Returns the name of this web framework.
085: *
086: * @return the name; never null.
087: */
088: public String getName() {
089: return this .name;
090: }
091:
092: /**
093: * Returns the description of this web framework. Defaults to the name
094: * if a null <code>description</code> parameter was passed to the constructor.
095: *
096: * @return the description; never null.
097: */
098: public String getDescription() {
099: if (description != null) {
100: return this .description;
101: }
102: return getName();
103: }
104:
105: /**
106: * Extends a web module with this web frameworks. For example it might be
107: * called in order to add the web framework to a newly created web application
108: * or in order to add the web framework to an existing application.
109: *
110: * @param wm the {@link org.netbeans.modules.web.api.webmodule.WebModule} to be extended; never null.
111: * @return the list of new files created in the web module as the result
112: * of extending it with this framework; never null.
113: *
114: * @deprecated This method has been replaced with {@link #createWebModuleExtender createWebModuleExtender}.
115: */
116: @Deprecated
117: public Set extend(WebModule wm) {
118: throw new IllegalStateException(
119: "This framework does not implemement the deprecated extend() method. Use createWebModuleExtender() instead."); // NOI18N
120: }
121:
122: /**
123: * Finds out if a given web module has already been extended with this framework.
124: *
125: * @param wm the web module; never null.
126: * @return true if the web module has already been extended with this framework, false otherwise.
127: */
128: public abstract boolean isInWebModule(WebModule wm);
129:
130: /**
131: * Returns the configuration files belonging to this framework.
132: *
133: * @param wm the web module for which the configuration files are returned; never null.
134: * @return an array containing the configuration files; never null.
135: */
136: public abstract File[] getConfigurationFiles(WebModule wm);
137:
138: /**
139: * Returns a configuration panel for this web framework. The panel is used
140: * to allow the user configure the way the web module will be extended.
141: * The configuration panel might be displayed to the user when creating
142: * a new web application or when editing the properties of an existing application.
143: *
144: * @param wm the web module to be configured.
145: * @return a configuration panel for this web framework.
146: *
147: * @deprecated This method has been replaced with {@link #createWebModuleExtender createWebModuleExtender}.
148: */
149: @Deprecated
150: public FrameworkConfigurationPanel getConfigurationPanel(
151: WebModule wm) {
152: throw new IllegalStateException(
153: "This framework does not implemement the deprecated getConfigurationPanel() method. Use createWebModuleExtender() instead."); // NOI18N
154: }
155:
156: /**
157: * Creates a {@link WebModuleExtender web module extender} for this framework
158: * and the given web module. This method needs to be implemented instead of the
159: * deprecated {@link #extend} and {@link #getConfigurationPanel} methods. It
160: * needs to be implemented even if this web framework doesn't support extending
161: * a web module (it would just return null in this case).
162: *
163: * @param wm the web module to be extended; can be null, e.g., if the
164: * method is called while creating a new web application, in which
165: * case the module doesn't exist yet.
166: * @param controller an instance of {@link ExtenderController} allowing the
167: * newly created extender to communicate with its environment. See the
168: * <code>ExtenderController</code> for details. Never null.
169: * @return a new web module extender; can be null if the framework doesn't support
170: * extending (either web modules in general of the particular web module
171: * passed in the <code>wm</code> parameter.
172: */
173: public WebModuleExtender createWebModuleExtender(WebModule wm,
174: ExtenderController controller) {
175: return WebModuleExtenderBridge.create(this , wm, controller);
176: }
177:
178: /**
179: * Returns the path of the request URL to a given file .
180: * This path starts with a "/" character and includes either the servlet name
181: * or a path to the servlet/JSP. Includes the servlet mapping, but does not include
182: * any extra path information or a query string. The method can return null.
183: *
184: * <p>JSF Example: consider an index.jsp file in the document base. Normaly the URL
185: * for accessing this page in browser should be <code>http://server:port/contextpath/index.jsp</code>.
186: * The servlet path is <code>/index.jsp</code>.</p>
187: *
188: * <p>However, because the <code>index.jsp</code> file includes JSF tags,
189: * its URL should include the appropriate JSF servlet
190: * mapping. If the mapping is /faces/*, then the URL is
191: * <code>http://server:port/contextpath/faces/index.jsp</code> and this method
192: * should return <code>/faces/index.jsp</code>.</p>
193: *
194: * @param file an arbitrary <code>FileObject</code>, usually a JSP file; never null.
195: * @return a string that contains the servlet path including the mapping; can be null.
196: */
197: public String getServletPath(FileObject file) {
198: return null;
199: }
200: }
|