You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by st...@apache.org on 2019/05/04 21:29:41 UTC
svn commit: r1858615 [9/32] - in /geronimo/specs/branches/jakarta:
geronimo-jakarta-jsp_spec/
geronimo-jakarta-jsp_spec/src/main/java/jakarta/servlet/jsp/
geronimo-jakarta-jsp_spec/src/main/java/jakarta/servlet/jsp/el/
geronimo-jakarta-jsp_spec/src/mai...
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextEvent.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextEvent.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextEvent.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextEvent.java Sat May 4 21:29:39 2019
@@ -1,40 +1,37 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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 javax.servlet;
-
+package jakarta.servlet;
/**
- * This is the event class for notifications about changes to
- * the servlet context of a web application.
+ * This is the event class for notifications about changes to the servlet
+ * context of a web application.
*
- * @version $Rev$ $Date$
* @see ServletContextListener
* @since v 2.3
*/
-
public class ServletContextEvent extends java.util.EventObject {
+ private static final long serialVersionUID = 1L;
+
/**
* Construct a ServletContextEvent from the given context.
*
- * @param source - the ServletContext that is sending the event.
+ * @param source
+ * - the ServletContext that is sending the event.
*/
public ServletContextEvent(ServletContext source) {
super(source);
@@ -48,6 +45,4 @@ public class ServletContextEvent extends
public ServletContext getServletContext() {
return (ServletContext) super.getSource();
}
-
}
-
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextListener.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextListener.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextListener.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletContextListener.java Sat May 4 21:29:39 2019
@@ -1,35 +1,29 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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 javax.servlet;
+package jakarta.servlet;
import java.util.EventListener;
/**
- * Implementations of this interface receive notifications about
- * changes to the servlet context of the web application they are
- * part of.
- * To receive notification events, the implementation class
- * must be configured in the deployment descriptor for the web
- * application.
+ * Implementations of this interface receive notifications about changes to the
+ * servlet context of the web application they are part of. To receive
+ * notification events, the implementation class must be configured in the
+ * deployment descriptor for the web application.
*
- * @version $Rev$ $Date$
* @see ServletContextEvent
* @since v 2.3
*/
@@ -37,21 +31,22 @@ import java.util.EventListener;
public interface ServletContextListener extends EventListener {
/**
- * Notification that the web application initialization
- * process is starting.
- * All ServletContextListeners are notified of context
- * initialization before any filter or servlet in the web
- * application is initialized.
+ ** Notification that the web application initialization process is starting.
+ * All ServletContextListeners are notified of context initialization before
+ * any filter or servlet in the web application is initialized.
+ * The default implementation is a NO-OP.
+ * @param sce Information about the ServletContext that was initialized
*/
- void contextInitialized(ServletContextEvent sce);
+ public default void contextInitialized(ServletContextEvent sce) {
+ }
/**
- * Notification that the servlet context is about to be shut down.
- * All servlets and filters have been destroy()ed before any
- * ServletContextListeners are notified of context
- * destruction.
+ ** Notification that the servlet context is about to be shut down. All
+ * servlets and filters have been destroy()ed before any
+ * ServletContextListeners are notified of context destruction.
+ * The default implementation is a NO-OP.
+ * @param sce Information about the ServletContext that was destroyed
*/
- void contextDestroyed(ServletContextEvent sce);
-
+ public default void contextDestroyed(ServletContextEvent sce) {
+ }
}
-
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletException.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletException.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletException.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletException.java Sat May 4 21:29:39 2019
@@ -1,34 +1,29 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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 javax.servlet;
-
+package jakarta.servlet;
/**
- * Defines a general exception a servlet can throw when it
- * encounters difficulty.
- *
- * @author Various
- * @version $Rev$ $Date$
+ * Defines a general exception a servlet can throw when it encounters
+ * difficulty.
*/
public class ServletException extends Exception {
+ private static final long serialVersionUID = 1L;
+
/**
* Constructs a new servlet exception.
*/
@@ -37,53 +32,49 @@ public class ServletException extends Ex
}
/**
- * Constructs a new servlet exception with the
- * specified message. The message can be written
- * to the server log and/or displayed for the user.
+ * Constructs a new servlet exception with the specified message. The
+ * message can be written to the server log and/or displayed for the user.
*
- * @param message a <code>String</code>
- * specifying the text of
- * the exception message
+ * @param message
+ * a <code>String</code> specifying the text of the exception
+ * message
*/
public ServletException(String message) {
super(message);
}
/**
- * Constructs a new servlet exception when the servlet
- * needs to throw an exception and include a message
- * about the "root cause" exception that interfered with its
- * normal operation, including a description message.
- *
- * @param message a <code>String</code> containing
- * the text of the exception message
- *
- * @param rootCause the <code>Throwable</code> exception
- * that interfered with the servlet's
- * normal operation, making this servlet
- * exception necessary
+ * Constructs a new servlet exception when the servlet needs to throw an
+ * exception and include a message about the "root cause" exception that
+ * interfered with its normal operation, including a description message.
+ *
+ * @param message
+ * a <code>String</code> containing the text of the exception
+ * message
+ * @param rootCause
+ * the <code>Throwable</code> exception that interfered with the
+ * servlet's normal operation, making this servlet exception
+ * necessary
*/
public ServletException(String message, Throwable rootCause) {
super(message, rootCause);
}
/**
- * Constructs a new servlet exception when the servlet
- * needs to throw an exception and include a message
- * about the "root cause" exception that interfered with its
- * normal operation. The exception's message is based on the localized
- * message of the underlying exception.
- *
- * <p>This method calls the <code>getLocalizedMessage</code> method
- * on the <code>Throwable</code> exception to get a localized exception
- * message. When subclassing <code>ServletException</code>,
- * this method can be overridden to create an exception message
- * designed for a specific locale.
- *
- * @param rootCause the <code>Throwable</code> exception
- * that interfered with the servlet's
- * normal operation, making the servlet exception
- * necessary
+ * Constructs a new servlet exception when the servlet needs to throw an
+ * exception and include a message about the "root cause" exception that
+ * interfered with its normal operation. The exception's message is based on
+ * the localized message of the underlying exception.
+ * <p>
+ * This method calls the <code>getLocalizedMessage</code> method on the
+ * <code>Throwable</code> exception to get a localized exception message.
+ * When subclassing <code>ServletException</code>, this method can be
+ * overridden to create an exception message designed for a specific locale.
+ *
+ * @param rootCause
+ * the <code>Throwable</code> exception that interfered with the
+ * servlet's normal operation, making the servlet exception
+ * necessary
*/
public ServletException(Throwable rootCause) {
super(rootCause);
@@ -92,8 +83,7 @@ public class ServletException extends Ex
/**
* Returns the exception that caused this servlet exception.
*
- * @return the <code>Throwable</code>
- * that caused this servlet exception
+ * @return the <code>Throwable</code> that caused this servlet exception
*/
public Throwable getRootCause() {
return getCause();
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletInputStream.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletInputStream.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletInputStream.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletInputStream.java Sat May 4 21:29:39 2019
@@ -1,86 +1,67 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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 javax.servlet;
+package jakarta.servlet;
import java.io.IOException;
import java.io.InputStream;
/**
- * Provides an input stream for reading binary data from a client
- * request, including an efficient <code>readLine</code> method
- * for reading data one line at a time. With some protocols, such
- * as HTTP POST and PUT, a <code>ServletInputStream</code>
- * object can be used to read data sent from the client.
- * <p/>
- * <p>A <code>ServletInputStream</code> object is normally retrieved via
- * the {@link ServletRequest#getInputStream} method.
- * <p/>
- * <p/>
- * <p>This is an abstract class that a servlet container implements.
- * Subclasses of this class
- * must implement the <code>java.io.InputStream.read()</code> method.
+ * Provides an input stream for reading binary data from a client request,
+ * including an efficient <code>readLine</code> method for reading data one line
+ * at a time. With some protocols, such as HTTP POST and PUT, a
+ * <code>ServletInputStream</code> object can be used to read data sent from the
+ * client.
+ * <p>
+ * A <code>ServletInputStream</code> object is normally retrieved via the
+ * {@link ServletRequest#getInputStream} method.
+ * <p>
+ * This is an abstract class that a servlet container implements. Subclasses of
+ * this class must implement the <code>java.io.InputStream.read()</code> method.
*
- * @version $Rev$ $Date$
- * @see ServletRequest
+ * @see ServletRequest
*/
-
public abstract class ServletInputStream extends InputStream {
/**
* Does nothing, because this is an abstract class.
*/
protected ServletInputStream() {
+ // NOOP
}
/**
- * Returns true when all the data from the stream has been read else it returns false.
- *
- * @return true when all data for this particular request has been read, otherwise returns false.
- * @since Servlet 3.1
- */
- public abstract boolean isFinished();
-
- /**
- * Returns true if data can be read without blocking else returns false.
- *
- * @return true if data can be obtained without blocking, otherwise returns false.
- * @since Servlet 3.1
- */
- public abstract boolean isReady();
-
- /**
- * Reads the input stream, one line at a time. Starting at an offset, reads bytes into an array, until it reads a
- * certain number of bytes or reaches a newline character, which it reads into the array as well.
- * <p/>
+ * Reads the input stream, one line at a time. Starting at an offset, reads
+ * bytes into an array, until it reads a certain number of bytes or reaches
+ * a newline character, which it reads into the array as well.
* <p>
- * This method returns -1 if it reaches the end of the input stream before reading the maximum number of bytes.
- *
+ * This method returns -1 if it reaches the end of the input stream before
+ * reading the maximum number of bytes.
+ *
* @param b
* an array of bytes into which data is read
* @param off
- * an integer specifying the character at which this method begins reading
+ * an integer specifying the character at which this method
+ * begins reading
* @param len
* an integer specifying the maximum number of bytes to read
- * @throws IOException
- * if an input or output exception has occurred
- * @return an integer specifying the actual number of bytes read, or -1 if the end of the stream is reached
+ * @return an integer specifying the actual number of bytes read, or -1 if
+ * the end of the stream is reached
+ * @exception IOException
+ * if an input or output exception has occurred
*/
public int readLine(byte[] b, int off, int len) throws IOException {
@@ -100,19 +81,41 @@ public abstract class ServletInputStream
}
/**
- * Instructs the ServletInputStream to invoke the provided ReadListener when it is possible to read.
- *
- * @param readListener
- * - the ReadListener that should be notified when it's possible to read.
- * @throws IllegalStateException
- * - if one of the following conditions is true
- * <ul>
- * <li>the associated request is neither upgraded nor the async started</li>
- * <li>setReadListener is called more than once within the scope of the same request.</li>
- * </ul>
- * @throws NullPointerException
- * - if readListener is null
+ * Has the end of this InputStream been reached?
+ *
+ * @return <code>true</code> if all the data has been read from the stream,
+ * else <code>false</code>
+ *
+ * @since Servlet 3.1
+ */
+ public abstract boolean isFinished();
+
+ /**
+ * Can data be read from this InputStream without blocking?
+ * Returns If this method is called and returns false, the container will
+ * invoke {@link ReadListener#onDataAvailable()} when data is available.
+ *
+ * @return <code>true</code> if data can be read without blocking, else
+ * <code>false</code>
+ *
+ * @since Servlet 3.1
+ */
+ public abstract boolean isReady();
+
+ /**
+ * Sets the {@link ReadListener} for this {@link ServletInputStream} and
+ * thereby switches to non-blocking IO. It is only valid to switch to
+ * non-blocking IO within async processing or HTTP upgrade processing.
+ *
+ * @param listener The non-blocking IO read listener
+ *
+ * @throws IllegalStateException If this method is called if neither
+ * async nor HTTP upgrade is in progress or
+ * if the {@link ReadListener} has already
+ * been set
+ * @throws NullPointerException If listener is null
+ *
* @since Servlet 3.1
*/
- public abstract void setReadListener(ReadListener readListener);
+ public abstract void setReadListener(ReadListener listener);
}
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletOutputStream.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletOutputStream.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletOutputStream.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletOutputStream.java Sat May 4 21:29:39 2019
@@ -1,75 +1,66 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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 jakarta.servlet;
-package javax.servlet;
-
-import java.io.OutputStream;
-import java.io.IOException;
import java.io.CharConversionException;
+import java.io.IOException;
+import java.io.OutputStream;
import java.text.MessageFormat;
import java.util.ResourceBundle;
/**
- * Provides an output stream for sending binary data to the
- * client. A <code>ServletOutputStream</code> object is normally retrieved
- * via the {@link ServletResponse#getOutputStream} method.
- * <p/>
- * <p>This is an abstract class that the servlet container implements.
- * Subclasses of this class
- * must implement the <code>java.io.OutputStream.write(int)</code>
+ * Provides an output stream for sending binary data to the client. A
+ * <code>ServletOutputStream</code> object is normally retrieved via the
+ * {@link ServletResponse#getOutputStream} method.
+ * <p>
+ * This is an abstract class that the servlet container implements. Subclasses
+ * of this class must implement the <code>java.io.OutputStream.write(int)</code>
* method.
*
- * @version $Rev$ $Date$
* @see ServletResponse
*/
-
public abstract class ServletOutputStream extends OutputStream {
private static final String LSTRING_FILE = "javax.servlet.LocalStrings";
- private static ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
+ private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
/**
* Does nothing, because this is an abstract class.
*/
protected ServletOutputStream() {
+ // NOOP
}
/**
- * This method can be used to determine if data can be written without blocking.
- *
- * @return true if a write to this ServletOutputStream will succeed, otherwise returns false.
- * @since Servlet 3.1
- */
- public abstract boolean isReady();
-
- /**
- * Writes a <code>String</code> to the client, without a carriage return-line feed (CRLF) character at the end.
- *
+ * Writes a <code>String</code> to the client, without a carriage
+ * return-line feed (CRLF) character at the end.
+ *
* @param s
* the <code>String</code> to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(String s) throws IOException {
- if (s == null)
+ if (s == null) {
s = "null";
+ }
int len = s.length();
+ byte[] buffer = new byte[len];
+
for (int i = 0; i < len; i++) {
char c = s.charAt(i);
@@ -82,21 +73,23 @@ public abstract class ServletOutputStrea
if ((c & 0xff00) != 0) { // high order byte must be zero
String errMsg = lStrings.getString("err.not_iso8859_1");
Object[] errArgs = new Object[1];
- errArgs[0] = c;
+ errArgs[0] = Character.valueOf(c);
errMsg = MessageFormat.format(errMsg, errArgs);
throw new CharConversionException(errMsg);
}
- write(c);
+ buffer[i] = (byte) (c & 0xFF);
}
+ write(buffer);
}
/**
- * Writes a <code>boolean</code> value to the client, with no carriage return-line feed (CRLF) character at the end.
- *
+ * Writes a <code>boolean</code> value to the client, with no carriage
+ * return-line feed (CRLF) character at the end.
+ *
* @param b
* the <code>boolean</code> value to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(boolean b) throws IOException {
String msg;
@@ -109,60 +102,65 @@ public abstract class ServletOutputStrea
}
/**
- * Writes a character to the client, with no carriage return-line feed (CRLF) at the end.
- *
+ * Writes a character to the client, with no carriage return-line feed
+ * (CRLF) at the end.
+ *
* @param c
* the character to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(char c) throws IOException {
print(String.valueOf(c));
}
/**
- * Writes an int to the client, with no carriage return-line feed (CRLF) at the end.
- *
+ * Writes an int to the client, with no carriage return-line feed (CRLF) at
+ * the end.
+ *
* @param i
* the int to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(int i) throws IOException {
print(String.valueOf(i));
}
/**
- * Writes a <code>long</code> value to the client, with no carriage return-line feed (CRLF) at the end.
- *
+ * Writes a <code>long</code> value to the client, with no carriage
+ * return-line feed (CRLF) at the end.
+ *
* @param l
* the <code>long</code> value to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(long l) throws IOException {
print(String.valueOf(l));
}
/**
- * Writes a <code>float</code> value to the client, with no carriage return-line feed (CRLF) at the end.
- *
+ * Writes a <code>float</code> value to the client, with no carriage
+ * return-line feed (CRLF) at the end.
+ *
* @param f
* the <code>float</code> value to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(float f) throws IOException {
print(String.valueOf(f));
}
/**
- * Writes a <code>double</code> value to the client, with no carriage return-line feed (CRLF) at the end.
- *
+ * Writes a <code>double</code> value to the client, with no carriage
+ * return-line feed (CRLF) at the end.
+ *
* @param d
* the <code>double</code> value to send to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void print(double d) throws IOException {
print(String.valueOf(d));
@@ -170,118 +168,142 @@ public abstract class ServletOutputStrea
/**
* Writes a carriage return-line feed (CRLF) to the client.
- *
- * @throws IOException
- * if an input or output exception occurred
+ *
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println() throws IOException {
print("\r\n");
}
/**
- * Writes a <code>String</code> to the client, followed by a carriage return-line feed (CRLF).
- *
+ * Writes a <code>String</code> to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
* @param s
* the <code>String</code> to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(String s) throws IOException {
- print(s);
- println();
+ StringBuilder sb = new StringBuilder();
+ sb.append(s);
+ sb.append("\r\n");
+ print(sb.toString());
}
/**
- * Writes a <code>boolean</code> value to the client, followed by a carriage return-line feed (CRLF).
- *
+ * Writes a <code>boolean</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
* @param b
* the <code>boolean</code> value to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(boolean b) throws IOException {
- print(b);
- println();
+ StringBuilder sb = new StringBuilder();
+ if (b) {
+ sb.append(lStrings.getString("value.true"));
+ } else {
+ sb.append(lStrings.getString("value.false"));
+ }
+ sb.append("\r\n");
+ print(sb.toString());
}
/**
- * Writes a character to the client, followed by a carriage return-line feed (CRLF).
- *
+ * Writes a character to the client, followed by a carriage return-line feed
+ * (CRLF).
+ *
* @param c
* the character to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(char c) throws IOException {
- print(c);
- println();
+ println(String.valueOf(c));
}
/**
- * Writes an int to the client, followed by a carriage return-line feed (CRLF) character.
- *
+ * Writes an int to the client, followed by a carriage return-line feed
+ * (CRLF) character.
+ *
* @param i
* the int to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(int i) throws IOException {
- print(i);
- println();
+ println(String.valueOf(i));
}
/**
- * Writes a <code>long</code> value to the client, followed by a carriage return-line feed (CRLF).
- *
+ * Writes a <code>long</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
* @param l
* the <code>long</code> value to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(long l) throws IOException {
- print(l);
- println();
+ println(String.valueOf(l));
}
/**
- * Writes a <code>float</code> value to the client, followed by a carriage return-line feed (CRLF).
- *
+ * Writes a <code>float</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
* @param f
* the <code>float</code> value to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(float f) throws IOException {
- print(f);
- println();
+ println(String.valueOf(f));
}
/**
- * Writes a <code>double</code> value to the client, followed by a carriage return-line feed (CRLF).
- *
+ * Writes a <code>double</code> value to the client, followed by a carriage
+ * return-line feed (CRLF).
+ *
* @param d
* the <code>double</code> value to write to the client
- * @throws IOException
- * if an input or output exception occurred
+ * @exception IOException
+ * if an input or output exception occurred
*/
public void println(double d) throws IOException {
- print(d);
- println();
+ println(String.valueOf(d));
}
/**
- * Instructs the ServletOutputStream to invoke the provided WriteListener when it is possible to write.
- *
- * @param writeListener
- * the WriteListener that should be notified when it's possible to write
- * @throws IllegalStateException
- * if one of the following conditions is true
- * <ul>
- * <li>the associated request is neither upgraded nor the async started</li>
- * <li>setWriteListener is called more than once within the scope of the same request.</li>
- * </ul>
- * @throws NullPointerException
- * if writeListener is null
+ * Checks if a non-blocking write will succeed. If this returns
+ * <code>false</code>, it will cause a callback to
+ * {@link WriteListener#onWritePossible()} when the buffer has emptied. If
+ * this method returns <code>false</code> no further data must be written
+ * until the contain calls {@link WriteListener#onWritePossible()}.
+ *
+ * @return <code>true</code> if data can be written, else <code>false</code>
+ *
+ * @since Servlet 3.1
+ */
+ public abstract boolean isReady();
+
+ /**
+ * Sets the {@link WriteListener} for this {@link ServletOutputStream} and
+ * thereby switches to non-blocking IO. It is only valid to switch to
+ * non-blocking IO within async processing or HTTP upgrade processing.
+ *
+ * @param listener The non-blocking IO write listener
+ *
+ * @throws IllegalStateException If this method is called if neither
+ * async nor HTTP upgrade is in progress or
+ * if the {@link WriteListener} has already
+ * been set
+ * @throws NullPointerException If listener is null
+ *
+ * @since Servlet 3.1
*/
- public abstract void setWriteListener(WriteListener writeListener);
+ public abstract void setWriteListener(javax.servlet.WriteListener listener);
}
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRegistration.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRegistration.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRegistration.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRegistration.java Sat May 4 21:29:39 2019
@@ -1,59 +1,49 @@
/*
- * 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.
- */
-
-
-package javax.servlet;
+* 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.
+*/
+package jakarta.servlet;
import java.util.Collection;
import java.util.Set;
/**
- * @version $Rev$ $Date$
- * @since 3.0
+ * TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
public interface ServletRegistration extends Registration {
/**
- *
- * @param urlPatterns patterns to map
- * @return patterns already mapped to another servlet
+ * TODO
+ * @param urlPatterns The URL patterns that this Servlet should be mapped to
+ * @return TODO
+ * @throws IllegalArgumentException if urlPattern is null or empty
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
- Set<String> addMapping(String... urlPatterns);
-
- Collection<String> getMappings();
-
- String getRunAsRole();
-
- public interface Dynamic extends ServletRegistration, Registration.Dynamic {
-
- void setLoadOnStartup(int loadOnStartup);
+ public Set<String> addMapping(String... urlPatterns);
- void setMultipartConfig(MultipartConfigElement element);
+ public Collection<String> getMappings();
- void setRunAsRole(String role);
+ public String getRunAsRole();
- /**
- *
- * @param securityElement
- * @return set of url mappings that were not changed
- */
- Set<String> setServletSecurity(ServletSecurityElement securityElement);
-
+ public static interface Dynamic
+ extends ServletRegistration, Registration.Dynamic {
+ public void setLoadOnStartup(int loadOnStartup);
+ public Set<String> setServletSecurity(ServletSecurityElement constraint);
+ public void setMultipartConfig(MultipartConfigElement multipartConfig);
+ public void setRunAsRole(String roleName);
}
}
Modified: geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRequest.java
URL: http://svn.apache.org/viewvc/geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRequest.java?rev=1858615&r1=1858614&r2=1858615&view=diff
==============================================================================
--- geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRequest.java (original)
+++ geronimo/specs/branches/jakarta/geronimo-jakarta-servlet_spec/src/main/java/jakarta/servlet/ServletRequest.java Sat May 4 21:29:39 2019
@@ -1,23 +1,20 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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 javax.servlet;
+package jakarta.servlet;
import java.io.BufferedReader;
import java.io.IOException;
@@ -26,477 +23,485 @@ import java.util.Locale;
import java.util.Map;
/**
- * Defines an object to provide client request information to a servlet. The
- * servlet container creates a <code>ServletRequest</code> object and passes
- * it as an argument to the servlet's <code>service</code> method.
- * <p/>
- * <p>A <code>ServletRequest</code> object provides data including
- * parameter name and values, attributes, and an input stream.
- * Interfaces that extend <code>ServletRequest</code> can provide
- * additional protocol-specific data (for example, HTTP data is
- * provided by {@link javax.servlet.http.HttpServletRequest}.
+ * Defines an object to provide client request information to a servlet. The
+ * servlet container creates a <code>ServletRequest</code> object and passes it
+ * as an argument to the servlet's <code>service</code> method.
+ * <p>
+ * A <code>ServletRequest</code> object provides data including parameter name
+ * and values, attributes, and an input stream. Interfaces that extend
+ * <code>ServletRequest</code> can provide additional protocol-specific data
+ * (for example, HTTP data is provided by
+ * {@link javax.servlet.http.HttpServletRequest}.
*
* @see javax.servlet.http.HttpServletRequest
- * @version $Rev$ $Date$
*/
-
public interface ServletRequest {
/**
- * @return async context
- * @since Servlet 3.0
+ * Returns the value of the named attribute as an <code>Object</code>, or
+ * <code>null</code> if no attribute of the given name exists.
+ * <p>
+ * Attributes can be set two ways. The servlet container may set attributes
+ * to make available custom information about a request. For example, for
+ * requests made using HTTPS, the attribute
+ * <code>javax.servlet.request.X509Certificate</code> can be used to
+ * retrieve information on the certificate of the client. Attributes can
+ * also be set programmatically using {@link ServletRequest#setAttribute}.
+ * This allows information to be embedded into a request before a
+ * {@link RequestDispatcher} call.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code> and <code>javax.*</code> are
+ * reserved for use by the Servlet specification. Names beginning with
+ * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
+ * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @return an <code>Object</code> containing the value of the attribute, or
+ * <code>null</code> if the attribute does not exist
+ */
+ public Object getAttribute(String name);
+
+ /**
+ * Returns an <code>Enumeration</code> containing the names of the
+ * attributes available to this request. This method returns an empty
+ * <code>Enumeration</code> if the request has no attributes available to
+ * it.
+ *
+ * @return an <code>Enumeration</code> of strings containing the names of the
+ * request's attributes
*/
- AsyncContext getAsyncContext();
+ public Enumeration<String> getAttributeNames();
/**
- * Returns the value of the named attribute as an <code>Object</code>,
- * or <code>null</code> if no attribute of the given name exists.
- * <p/>
- * <p> Attributes can be set two ways. The servlet container may set
- * attributes to make available custom information about a request.
- * For example, for requests made using HTTPS, the attribute
- * <code>javax.servlet.request.X509Certificate</code> can be used to
- * retrieve information on the certificate of the client. Attributes
- * can also be set programatically using
- * {@link ServletRequest#setAttribute}. This allows information to be
- * embedded into a request before a {@link RequestDispatcher} call.
- * <p/>
- * <p>Attribute names should follow the same conventions as package
- * names. This specification reserves names matching <code>java.*</code>,
- * <code>javax.*</code>, and <code>sun.*</code>.
- *
- * @param name a <code>String</code> specifying the name of
- * the attribute
- * @return an <code>Object</code> containing the value
- * of the attribute, or <code>null</code> if
- * the attribute does not exist
- */
- Object getAttribute(String name);
-
- /**
- * Returns an <code>Enumeration</code> containing the
- * names of the attributes available to this request.
- * This method returns an empty <code>Enumeration</code>
- * if the request has no attributes available to it.
- *
- * @return an <code>Enumeration</code> of strings
- * containing the names
- * of the request's attributes
+ * Returns the name of the character encoding used in the body of this
+ * request. This method returns <code>null</code> if the no character
+ * encoding has been specified. The following priority order is used to
+ * determine the specified encoding:
+ * <ol>
+ * <li>per request</li>
+ * <li>web application default via the deployment descriptor or
+ * {@link ServletContext#setRequestCharacterEncoding(String)}</li>
+ * <li>container default via container specific configuration</li>
+ * </ol>
+ *
+ * @return a <code>String</code> containing the name of the character
+ * encoding, or <code>null</code> if the request does not specify a
+ * character encoding
*/
- Enumeration<String> getAttributeNames();
+ public String getCharacterEncoding();
/**
- * Returns the name of the character encoding used in the body of this
- * request. This method returns <code>null</code> if the request
- * does not specify a character encoding
+ * Overrides the name of the character encoding used in the body of this
+ * request. This method must be called prior to reading request parameters
+ * or reading input using getReader().
*
- * @return a <code>String</code> containing the name of
- * the character encoding, or <code>null</code>
- * if the request does not specify a character encoding
+ * @param env
+ * a <code>String</code> containing the name of the character
+ * encoding.
+ * @throws java.io.UnsupportedEncodingException
+ * if this is not a valid encoding
*/
- String getCharacterEncoding();
+ public void setCharacterEncoding(String env)
+ throws java.io.UnsupportedEncodingException;
/**
- * Returns the length, in bytes, of the request body
- * and made available by the input stream, or -1 if the
- * length is not known. For HTTP servlets, same as the value
- * of the CGI variable CONTENT_LENGTH.
+ * Returns the length, in bytes, of the request body and made available by
+ * the input stream, or -1 if the length is not known. For HTTP servlets,
+ * same as the value of the CGI variable CONTENT_LENGTH.
*
- * @return an integer containing the length of the
- * request body or -1 if the length is not known
+ * @return an integer containing the length of the request body or -1 if the
+ * length is not known or is greater than {@link Integer#MAX_VALUE}
*/
- int getContentLength();
+ public int getContentLength();
/**
- * Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is
- * not known. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH.
- *
+ * Returns the length, in bytes, of the request body and made available by
+ * the input stream, or -1 if the length is not known. For HTTP servlets,
+ * same as the value of the CGI variable CONTENT_LENGTH.
+ *
+ * @return a long integer containing the length of the request body or -1 if
+ * the length is not known
* @since Servlet 3.1
- * @return a long containing the length of the request body or -1L if the length is not known
*/
- long getContentLengthLong();
+ public long getContentLengthLong();
/**
- * Returns the MIME type of the body of the request, or
- * <code>null</code> if the type is not known. For HTTP servlets,
- * same as the value of the CGI variable CONTENT_TYPE.
- *
- * @return a <code>String</code> containing the name
- * of the MIME type of
- * the request, or null if the type is not known
+ * Returns the MIME type of the body of the request, or <code>null</code> if
+ * the type is not known. For HTTP servlets, same as the value of the CGI
+ * variable CONTENT_TYPE.
+ *
+ * @return a <code>String</code> containing the name of the MIME type of the
+ * request, or null if the type is not known
+ */
+ public String getContentType();
+
+ /**
+ * Retrieves the body of the request as binary data using a
+ * {@link ServletInputStream}. Either this method or {@link #getReader} may
+ * be called to read the body, not both.
+ *
+ * @return a {@link ServletInputStream} object containing the body of the
+ * request
+ * @exception IllegalStateException
+ * if the {@link #getReader} method has already been called
+ * for this request
+ * @exception IOException
+ * if an input or output exception occurred
+ */
+ public ServletInputStream getInputStream() throws IOException;
+
+ /**
+ * Returns the value of a request parameter as a <code>String</code>, or
+ * <code>null</code> if the parameter does not exist. Request parameters are
+ * extra information sent with the request. For HTTP servlets, parameters
+ * are contained in the query string or posted form data.
+ * <p>
+ * You should only use this method when you are sure the parameter has only
+ * one value. If the parameter might have more than one value, use
+ * {@link #getParameterValues}.
+ * <p>
+ * If you use this method with a multivalued parameter, the value returned
+ * is equal to the first value in the array returned by
+ * <code>getParameterValues</code>.
+ * <p>
+ * If the parameter data was sent in the request body, such as occurs with
+ * an HTTP POST request, then reading the body directly via
+ * {@link #getInputStream} or {@link #getReader} can interfere with the
+ * execution of this method.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the parameter
+ * @return a <code>String</code> representing the single value of the
+ * parameter
+ * @see #getParameterValues
*/
- String getContentType();
+ public String getParameter(String name);
/**
- * @since Servlet 3.0
- * @return dispatcher type
+ * Returns an <code>Enumeration</code> of <code>String</code> objects
+ * containing the names of the parameters contained in this request. If the
+ * request has no parameters, the method returns an empty
+ * <code>Enumeration</code>.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects, each
+ * <code>String</code> containing the name of a request parameter;
+ * or an empty <code>Enumeration</code> if the request has no
+ * parameters
*/
- DispatcherType getDispatcherType();
+ public Enumeration<String> getParameterNames();
/**
- * Retrieves the body of the request as binary data using
- * a {@link ServletInputStream}. Either this method or
- * {@link #getReader} may be called to read the body, not both.
+ * Returns an array of <code>String</code> objects containing all of the
+ * values the given request parameter has, or <code>null</code> if the
+ * parameter does not exist.
+ * <p>
+ * If the parameter has a single value, the array has a length of 1.
*
- * @return a {@link ServletInputStream} object containing
- * the body of the request
- * @throws IllegalStateException if the {@link #getReader} method
- * has already been called for this request
- * @throws IOException if an input or output exception occurred
+ * @param name
+ * a <code>String</code> containing the name of the parameter
+ * whose value is requested
+ * @return an array of <code>String</code> objects containing the parameter's
+ * values
+ * @see #getParameter
*/
- ServletInputStream getInputStream() throws IOException;
+ public String[] getParameterValues(String name);
/**
- * Returns the Internet Protocol (IP) address of the interface on
- * which the request was received.
+ * Returns a java.util.Map of the parameters of this request. Request
+ * parameters are extra information sent with the request. For HTTP
+ * servlets, parameters are contained in the query string or posted form
+ * data.
*
- * @return a <code>String</code> containing the
- * IP address on which the request was received.
- * @since 2.4
+ * @return an immutable java.util.Map containing parameter names as keys and
+ * parameter values as map values. The keys in the parameter map are
+ * of type String. The values in the parameter map are of type
+ * String array.
*/
- String getLocalAddr();
+ public Map<String, String[]> getParameterMap();
/**
- * Returns the preferred <code>Locale</code> that the client will
- * accept content in, based on the Accept-Language header.
- * If the client request doesn't provide an Accept-Language header,
- * this method returns the default locale for the server.
+ * Returns the name and version of the protocol the request uses in the form
+ * <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1. For
+ * HTTP servlets, the value returned is the same as the value of the CGI
+ * variable <code>SERVER_PROTOCOL</code>.
*
- * @return the preferred <code>Locale</code> for the client
+ * @return a <code>String</code> containing the protocol name and version
+ * number
*/
- Locale getLocale();
+ public String getProtocol();
/**
- * Returns an <code>Enumeration</code> of <code>Locale</code> objects
- * indicating, in decreasing order starting with the preferred locale, the
- * locales that are acceptable to the client based on the Accept-Language
- * header.
- * If the client request doesn't provide an Accept-Language header,
- * this method returns an <code>Enumeration</code> containing one
- * <code>Locale</code>, the default locale for the server.
+ * Returns the name of the scheme used to make this request, for example,
+ * <code>http</code>, <code>https</code>, or <code>ftp</code>. Different
+ * schemes have different rules for constructing URLs, as noted in RFC 1738.
*
- * @return an <code>Enumeration</code> of preferred
- * <code>Locale</code> objects for the client
+ * @return a <code>String</code> containing the name of the scheme used to
+ * make this request
*/
- Enumeration<Locale> getLocales();
+ public String getScheme();
/**
- * Returns the host name of the Internet Protocol (IP) interface on
- * which the request was received.
+ * Returns the host name of the server to which the request was sent. It is
+ * the value of the part before ":" in the <code>Host</code> header value,
+ * if any, or the resolved server name, or the server IP address.
*
- * @return a <code>String</code> containing the host
- * name of the IP on which the request was received.
- * @since 2.4
+ * @return a <code>String</code> containing the name of the server
*/
- String getLocalName();
+ public String getServerName();
/**
- * Returns the Internet Protocol (IP) port number of the interface
- * on which the request was received.
+ * Returns the port number to which the request was sent. It is the value of
+ * the part after ":" in the <code>Host</code> header value, if any, or the
+ * server port where the client connection was accepted on.
*
* @return an integer specifying the port number
- * @since 2.4
*/
- int getLocalPort();
+ public int getServerPort();
- /**
- * Returns the value of a request parameter as a <code>String</code>,
- * or <code>null</code> if the parameter does not exist. Request parameters
- * are extra information sent with the request. For HTTP servlets,
- * parameters are contained in the query string or posted form data.
- * <p/>
- * <p>You should only use this method when you are sure the
- * parameter has only one value. If the parameter might have
- * more than one value, use {@link #getParameterValues}.
- * <p/>
- * <p>If you use this method with a multivalued
- * parameter, the value returned is equal to the first value
- * in the array returned by <code>getParameterValues</code>.
- * <p/>
- * <p>If the parameter data was sent in the request body, such as occurs
- * with an HTTP POST request, then reading the body directly via {@link
- * #getInputStream} or {@link #getReader} can interfere
- * with the execution of this method.
- *
- * @param name a <code>String</code> specifying the
- * name of the parameter
- * @return a <code>String</code> representing the
- * single value of the parameter
- * @see #getParameterValues
+ /**
+ * Retrieves the body of the request as character data using a
+ * <code>BufferedReader</code>. The reader translates the character data
+ * according to the character encoding used on the body. Either this method
+ * or {@link #getInputStream} may be called to read the body, not both.
+ *
+ * @return a <code>BufferedReader</code> containing the body of the request
+ * @exception java.io.UnsupportedEncodingException
+ * if the character set encoding used is not supported and
+ * the text cannot be decoded
+ * @exception IllegalStateException
+ * if {@link #getInputStream} method has been called on this
+ * request
+ * @exception IOException
+ * if an input or output exception occurred
+ * @see #getInputStream
*/
- String getParameter(String name);
+ public BufferedReader getReader() throws IOException;
/**
- * Returns a java.util.Map of the parameters of this request.
- * Request parameters
- * are extra information sent with the request. For HTTP servlets,
- * parameters are contained in the query string or posted form data.
+ * Returns the Internet Protocol (IP) address of the client or last proxy
+ * that sent the request. For HTTP servlets, same as the value of the CGI
+ * variable <code>REMOTE_ADDR</code>.
*
- * @return an immutable java.util.Map containing parameter names as
- * keys and parameter values as map values. The keys in the parameter
- * map are of type String. The values in the parameter map are of type
- * String array.
+ * @return a <code>String</code> containing the IP address of the client
+ * that sent the request
*/
- Map<String, String[]> getParameterMap();
+ public String getRemoteAddr();
/**
- * Returns an <code>Enumeration</code> of <code>String</code>
- * objects containing the names of the parameters contained
- * in this request. If the request has
- * no parameters, the method returns an
- * empty <code>Enumeration</code>.
- *
- * @return an <code>Enumeration</code> of <code>String</code>
- * objects, each <code>String</code> containing
- * the name of a request parameter; or an
- * empty <code>Enumeration</code> if the
- * request has no parameters
- */
- Enumeration<String> getParameterNames();
-
- /**
- * Returns an array of <code>String</code> objects containing
- * all of the values the given request parameter has, or
- * <code>null</code> if the parameter does not exist.
- * <p/>
- * <p>If the parameter has a single value, the array has a length
- * of 1.
- *
- * @param name a <code>String</code> containing the name of
- * the parameter whose value is requested
- * @return an array of <code>String</code> objects
- * containing the parameter's values
- * @see #getParameter
+ * Returns the fully qualified name of the client or the last proxy that
+ * sent the request. If the engine cannot or chooses not to resolve the
+ * hostname (to improve performance), this method returns the dotted-string
+ * form of the IP address. For HTTP servlets, same as the value of the CGI
+ * variable <code>REMOTE_HOST</code>.
+ *
+ * @return a <code>String</code> containing the fully qualified name of the
+ * client
*/
+ public String getRemoteHost();
- String[] getParameterValues(String name);
+ /**
+ * Stores an attribute in this request. Attributes are reset between
+ * requests. This method is most often used in conjunction with
+ * {@link RequestDispatcher}.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code> and <code>javax.*</code> are
+ * reserved for use by the Servlet specification. Names beginning with
+ * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
+ * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
+ * <br>
+ * If the object passed in is null, the effect is the same as calling
+ * {@link #removeAttribute}. <br>
+ * It is warned that when the request is dispatched from the servlet resides
+ * in a different web application by <code>RequestDispatcher</code>, the
+ * object set by this method may not be correctly retrieved in the caller
+ * servlet.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @param o
+ * the <code>Object</code> to be stored
+ */
+ public void setAttribute(String name, Object o);
/**
- * Returns the name and version of the protocol the request uses
- * in the form <i>protocol/majorVersion.minorVersion</i>, for
- * example, HTTP/1.1. For HTTP servlets, the value
- * returned is the same as the value of the CGI variable
- * <code>SERVER_PROTOCOL</code>.
+ * Removes an attribute from this request. This method is not generally
+ * needed as attributes only persist as long as the request is being
+ * handled.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code> and <code>javax.*</code> are
+ * reserved for use by the Servlet specification. Names beginning with
+ * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
+ * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
*
- * @return a <code>String</code> containing the protocol
- * name and version number
+ * @param name
+ * a <code>String</code> specifying the name of the attribute to
+ * remove
*/
- String getProtocol();
+ public void removeAttribute(String name);
/**
- * Retrieves the body of the request as character data using
- * a <code>BufferedReader</code>. The reader translates the character
- * data according to the character encoding used on the body.
- * Either this method or {@link #getInputStream} may be called to read the
- * body, not both.
+ * Returns the preferred <code>Locale</code> that the client will accept
+ * content in, based on the Accept-Language header. If the client request
+ * doesn't provide an Accept-Language header, this method returns the
+ * default locale for the server.
*
- * @return a <code>BufferedReader</code>
- * containing the body of the request
- * @throws java.io.UnsupportedEncodingException
- * if the character set encoding
- * used is not supported and the
- * text cannot be decoded
- * @throws IllegalStateException if {@link #getInputStream} method
- * has been called on this request
- * @throws IOException if an input or output exception occurred
- * @see #getInputStream
+ * @return the preferred <code>Locale</code> for the client
*/
- BufferedReader getReader() throws IOException;
+ public Locale getLocale();
/**
- * @deprecated As of Version 2.1 of the Java Servlet API,
- * use {@link ServletContext#getRealPath} instead.
+ * Returns an <code>Enumeration</code> of <code>Locale</code> objects
+ * indicating, in decreasing order starting with the preferred locale, the
+ * locales that are acceptable to the client based on the Accept-Language
+ * header. If the client request doesn't provide an Accept-Language header,
+ * this method returns an <code>Enumeration</code> containing one
+ * <code>Locale</code>, the default locale for the server.
+ *
+ * @return an <code>Enumeration</code> of preferred <code>Locale</code>
+ * objects for the client
*/
- String getRealPath(String path);
+ public Enumeration<Locale> getLocales();
/**
- * Returns the Internet Protocol (IP) address of the client
- * or last proxy that sent the request.
- * For HTTP servlets, same as the value of the
- * CGI variable <code>REMOTE_ADDR</code>.
- *
- * @return a <code>String</code> containing the
- * IP address of the client that sent the request
- */
- String getRemoteAddr();
-
- /**
- * Returns the fully qualified name of the client
- * or the last proxy that sent the request.
- * If the engine cannot or chooses not to resolve the hostname
- * (to improve performance), this method returns the dotted-string form of
- * the IP address. For HTTP servlets, same as the value of the CGI variable
- * <code>REMOTE_HOST</code>.
- *
- * @return a <code>String</code> containing the fully
- * qualified name of the client
- */
- String getRemoteHost();
-
- /**
- * Returns the Internet Protocol (IP) source port of the client
- * or last proxy that sent the request.
- *
- * @return an integer specifying the port number
- * @since 2.4
- */
- int getRemotePort();
-
- /**
- * Returns a {@link RequestDispatcher} object that acts as a wrapper for
- * the resource located at the given path.
- * A <code>RequestDispatcher</code> object can be used to forward
- * a request to the resource or to include the resource in a response.
- * The resource can be dynamic or static.
- * <p/>
- * <p>The pathname specified may be relative, although it cannot extend
- * outside the current servlet context. If the path begins with
- * a "/" it is interpreted as relative to the current context root.
- * This method returns <code>null</code> if the servlet container
- * cannot return a <code>RequestDispatcher</code>.
- * <p/>
- * <p>The difference between this method and {@link
- * ServletContext#getRequestDispatcher} is that this method can take a
- * relative path.
- *
- * @param path a <code>String</code> specifying the pathname
- * to the resource. If it is relative, it must be
- * relative against the current servlet.
- * @return a <code>RequestDispatcher</code> object
- * that acts as a wrapper for the resource
- * at the specified path, or <code>null</code>
- * if the servlet container cannot return a
- * <code>RequestDispatcher</code>
+ * Returns a boolean indicating whether this request was made using a secure
+ * channel, such as HTTPS.
+ *
+ * @return a boolean indicating if the request was made using a secure
+ * channel
+ */
+ public boolean isSecure();
+
+ /**
+ * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
+ * resource located at the given path. A <code>RequestDispatcher</code>
+ * object can be used to forward a request to the resource or to include the
+ * resource in a response. The resource can be dynamic or static.
+ * <p>
+ * The pathname specified may be relative, although it cannot extend outside
+ * the current servlet context. If the path begins with a "/" it is
+ * interpreted as relative to the current context root. This method returns
+ * <code>null</code> if the servlet container cannot return a
+ * <code>RequestDispatcher</code>.
+ * <p>
+ * The difference between this method and
+ * {@link ServletContext#getRequestDispatcher} is that this method can take
+ * a relative path.
+ *
+ * @param path
+ * a <code>String</code> specifying the pathname to the resource.
+ * If it is relative, it must be relative against the current
+ * servlet.
+ * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
+ * the resource at the specified path, or <code>null</code> if the
+ * servlet container cannot return a <code>RequestDispatcher</code>
* @see RequestDispatcher
* @see ServletContext#getRequestDispatcher
*/
- RequestDispatcher getRequestDispatcher(String path);
+ public RequestDispatcher getRequestDispatcher(String path);
/**
- * Returns the name of the scheme used to make this request,
- * for example,
- * <code>http</code>, <code>https</code>, or <code>ftp</code>.
- * Different schemes have different rules for constructing URLs,
- * as noted in RFC 1738.
- *
- * @return a <code>String</code> containing the name
- * of the scheme used to make this request
+ * @param path The virtual path to be converted to a real path
+ * @return {@link ServletContext#getRealPath(String)}
+ * @deprecated As of Version 2.1 of the Java Servlet API, use
+ * {@link ServletContext#getRealPath} instead.
*/
- String getScheme();
+ @Deprecated
+ public String getRealPath(String path);
/**
- * Returns the host name of the server to which the request was sent.
- * It is the value of the part before ":" in the <code>Host</code>
- * header value, if any, or the resolved server name, or the server IP address.
+ * Returns the Internet Protocol (IP) source port of the client or last
+ * proxy that sent the request.
*
- * @return a <code>String</code> containing the name
- * of the server
+ * @return an integer specifying the port number
+ * @since Servlet 2.4
*/
- String getServerName();
+ public int getRemotePort();
/**
- * Returns the port number to which the request was sent.
- * It is the value of the part after ":" in the <code>Host</code>
- * header value, if any, or the server port where the client connection
- * was accepted on.
+ * Returns the host name of the Internet Protocol (IP) interface on which
+ * the request was received.
*
- * @return an integer specifying the port number
+ * @return a <code>String</code> containing the host name of the IP on which
+ * the request was received.
+ * @since Servlet 2.4
*/
- int getServerPort();
+ public String getLocalName();
/**
- * Get the servlet context the request-response pair was last dispatched through.
- *
- * @return the latest ServletContext on the dispatch chain.
- * @since 3.0
- */
- ServletContext getServletContext();
+ * Returns the Internet Protocol (IP) address of the interface on which the
+ * request was received.
+ *
+ * @return a <code>String</code> containing the IP address on which the
+ * request was received.
+ * @since Servlet 2.4
+ */
+ public String getLocalAddr();
/**
- * @since Servlet 3.0
- * @return if async is started
+ * Returns the Internet Protocol (IP) port number of the interface on which
+ * the request was received.
+ *
+ * @return an integer specifying the port number
+ * @since Servlet 2.4
*/
- boolean isAsyncStarted();
+ public int getLocalPort();
/**
- * @since Servlet 3.0
- * @return if async is supported
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- boolean isAsyncSupported();
+ public ServletContext getServletContext();
/**
- * Returns a boolean indicating whether this request was made using a
- * secure channel, such as HTTPS.
- *
- * @return a boolean indicating if the request was made using a
- * secure channel
+ * @return TODO
+ * @throws IllegalStateException If async is not supported for this request
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- boolean isSecure();
+ public AsyncContext startAsync() throws IllegalStateException;
/**
- * Removes an attribute from this request. This method is not
- * generally needed as attributes only persist as long as the request
- * is being handled.
- * <p/>
- * <p>Attribute names should follow the same conventions as
- * package names. Names beginning with <code>java.*</code>,
- * <code>javax.*</code>, and <code>com.sun.*</code>, are
- * reserved for use by Sun Microsystems.
- *
- * @param name a <code>String</code> specifying
- * the name of the attribute to remove
+ * @param servletRequest The ServletRequest with which to initialise the
+ * asynchronous context
+ * @param servletResponse The ServletResponse with which to initialise the
+ * asynchronous context
+ * @return TODO
+ * @throws IllegalStateException If async is not supported for this request
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- void removeAttribute(String name);
+ public AsyncContext startAsync(ServletRequest servletRequest,
+ ServletResponse servletResponse) throws IllegalStateException;
/**
- * Stores an attribute in this request.
- * Attributes are reset between requests. This method is most
- * often used in conjunction with {@link RequestDispatcher}.
- * <p/>
- * <p>Attribute names should follow the same conventions as
- * package names. Names beginning with <code>java.*</code>,
- * <code>javax.*</code>, and <code>com.sun.*</code>, are
- * reserved for use by Sun Microsystems.
- * <br> If the object passed in is null, the effect is the same as
- * calling {@link #removeAttribute}.
- * <br> It is warned that when the request is dispatched from the
- * servlet resides in a different web application by
- * <code>RequestDispatcher</code>, the object set by this method
- * may not be correctly retrieved in the caller servlet.
- *
- * @param name a <code>String</code> specifying
- * the name of the attribute
- * @param o the <code>Object</code> to be stored
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- void setAttribute(String name, Object o);
-
+ public boolean isAsyncStarted();
+
/**
- * Overrides the name of the character encoding used in the body of this
- * request. This method must be called prior to reading request parameters
- * or reading input using getReader().
- *
- * @param env a <code>String</code> containing the name of
- * the character encoding.
- * @throws java.io.UnsupportedEncodingException
- * if this is not a valid encoding
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException;
+ public boolean isAsyncSupported();
/**
+ * Get the current AsyncContext.
+ *
+ * @return The current AsyncContext
+ *
+ * @throws IllegalStateException if the request is not in asynchronous mode
+ * (i.e. @link #isAsyncStarted() is {@code false})
*
- * @return AsyncContext to control further work, initialized with the original request and response
- * @since 3.0
+ * @since Servlet 3.0
*/
- AsyncContext startAsync();
+ public AsyncContext getAsyncContext();
/**
- *
- * @param request servlet request
- * @param response servlet response
- * @return AsyncContext to control further work, initialized with the supplied request and response
- * @since 3.0
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
- AsyncContext startAsync(ServletRequest request, ServletResponse response);
-
+ public DispatcherType getDispatcherType();
}
-