Use snippet in javadoc,

fix typos, grammar

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>

.github/workflows/maven.yml

@@ -23,7 +23,7 @@ jobs:
 
     strategy:
       matrix:
-        java_version: [ 17, 21 ]
+        java_version: [ 21 ]
 
     steps:
     - name: Checkout for build

api/README.md

@@ -1,4 +1,4 @@
-[//]: # " Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved. "
+[//]: # " Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved. "
 [//]: # "  "
 [//]: # " This program and the accompanying materials are made available under the "
 [//]: # " terms of the Eclipse Distribution License v. 1.0, which is available at "
@@ -16,8 +16,8 @@ Building
 
 Prerequisites:
 
-* JDK11+
-* Maven 3.6+
+* JDK18+
+* Maven 3.6.3+
 
 Run the full build:
 

api/src/main/java/jakarta/xml/soap/AttachmentPart.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -34,15 +34,15 @@
  *       This header identifies the type of data in the content of an
  *       {@code AttachmentPart} object and MUST conform to [RFC2045].
  *       The following is an example of a Content-Type header:
- *       <PRE>
- *       Content-Type:  application/xml
- *       </PRE>
+ *       {@snippet :
+ *        Content-Type:  application/xml
+ *       }
  *       The following line of code, in which {@code ap} is an
  *       {@code AttachmentPart} object, sets the header shown in
  *       the previous example.
- *       <PRE>
- *       ap.setMimeHeader("Content-Type", "application/xml");
- *       </PRE>
+ *       {@snippet :
+ *        ap.setMimeHeader("Content-Type", "application/xml");
+ *       }
  *  </UL>
  * </OL>
  * <p>
@@ -58,45 +58,45 @@
  *
  * <p>
  * The following code fragment, in which {@code m} is a
- * {@code SOAPMessage} object and {@code contentStringl} is a
+ * {@code SOAPMessage} object and {@code contentString} is a
  * {@code String}, creates an instance of {@code AttachmentPart},
  * sets the {@code AttachmentPart} object with some content and
  * header information, and adds the {@code AttachmentPart} object to
  * the {@code SOAPMessage} object.
- * <PRE>
- *     AttachmentPart ap1 = m.createAttachmentPart();
- *     ap1.setContent(contentString1, "text/plain");
- *     m.addAttachmentPart(ap1);
- * </PRE>
+ * {@snippet :
+ *  AttachmentPart ap1 = m.createAttachmentPart();
+ *  ap1.setContent(contentString1, "text/plain");
+ *  m.addAttachmentPart(ap1);
+ * }
  *
  *
  * <p>
  * The following code fragment creates and adds a second
  * {@code AttachmentPart} instance to the same message. {@code jpegData}
  * is a binary byte buffer representing the jpeg file.
- * <PRE>
- *     AttachmentPart ap2 = m.createAttachmentPart();
- *     byte[] jpegData =  ...;
- *     ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
- *     m.addAttachmentPart(ap2);
- * </PRE>
+ * {@snippet :
+ *  AttachmentPart ap2 = m.createAttachmentPart();
+ *  byte[] jpegData =  ...;
+ *  ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
+ *  m.addAttachmentPart(ap2);
+ * }
  * <p>
  * The {@code getContent} method retrieves the contents and header from
  * an {@code AttachmentPart} object. Depending on the
  * {@code DataContentHandler} objects present, the returned
  * {@code Object} can either be a typed Java object corresponding
  * to the MIME type or an {@code InputStream} object that contains the
  * content as bytes.
- * <PRE>
- *     String content1 = ap1.getContent();
- *     java.io.InputStream content2 = ap2.getContent();
- * </PRE>
+ * {@snippet :
+ *  String content1 = ap1.getContent();
+ *  java.io.InputStream content2 = ap2.getContent();
+ * }
  *
  * The method {@code clearContent} removes all the content from an
  * {@code AttachmentPart} object but does not affect its header information.
- * <PRE>
- *     ap1.clearContent();
- * </PRE>
+ * {@snippet :
+ *  ap1.clearContent();
+ * }
  *
  * @since 1.6
  */
@@ -257,7 +257,7 @@ protected AttachmentPart() {
      * @param contentType the value to set into the {@code Content-Type}
      * header
      *
-     * @exception SOAPException if an there is an error in setting the content
+     * @exception SOAPException if there is an error in setting the content
      * @exception NullPointerException if {@code content} is null
      * @since 1.6, SAAJ 1.3
      */
@@ -275,7 +275,7 @@ protected AttachmentPart() {
      * @param offset the offset in the byte array of the content
      * @param len the number of bytes that form the content
      *
-     * @exception SOAPException if an there is an error in setting the content
+     * @exception SOAPException if there is an error in setting the content
      * or content is null
      * @since 1.6, SAAJ 1.3
      */
@@ -298,7 +298,7 @@ public abstract void setRawContentBytes(
      * @param contentType the value to set into the {@code Content-Type}
      * header
      *
-     * @exception SOAPException if an there is an error in setting the content
+     * @exception SOAPException if there is an error in setting the content
      * @exception NullPointerException if {@code content} is null
      *
      * @since 1.6, SAAJ 1.3
@@ -487,7 +487,7 @@ public void setContentType(String contentType)
      * Retrieves all the headers for this {@code AttachmentPart} object
      * as an iterator over the {@code MimeHeader} objects.
      *
-     * @return  an {@code Iterator} object with all of the Mime
+     * @return  an {@code Iterator} object with all the Mime
      *          headers for this {@code AttachmentPart} object
      */
     public abstract Iterator<MimeHeader> getAllMimeHeaders();
@@ -498,7 +498,7 @@ public void setContentType(String contentType)
      *
      * @param names a {@code String} array with the name(s) of the
      *        MIME headers to be returned
-     * @return  all of the MIME headers that match one of the names in the
+     * @return  all the MIME headers that match one of the names in the
      *           given array as an {@code Iterator} object
      */
     public abstract Iterator<MimeHeader> getMatchingMimeHeaders(String[] names);
@@ -509,7 +509,7 @@ public void setContentType(String contentType)
      *
      * @param names a {@code String} array with the name(s) of the
      *        MIME headers not to be returned
-     * @return  all of the MIME headers in this {@code AttachmentPart} object
+     * @return  all the MIME headers in this {@code AttachmentPart} object
      *          except those that match one of the names in the
      *           given array.  The nonmatching MIME headers are returned as an
      *           {@code Iterator} object.

api/src/main/java/jakarta/xml/soap/Detail.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -34,13 +34,13 @@
  * {@code Name} object to pass to the method {@code addDetailEntry}.
  * The variable <i>se</i>, used to create the {@code Name} object,
  * is a {@code SOAPEnvelope} object.
- * <pre>{@code
- *    Detail d = sf.getDetail();
- *    Name name = se.createName("GetLastTradePrice", "WOMBAT",
- *                                "http://www.wombat.org/trader");
- *    d.addDetailEntry(name);
- *    Iterator<DetailEntry> it = d.getDetailEntries();
- * }</pre>
+ * {@snippet :
+ *  Detail d = sf.getDetail();
+ *  Name name = se.createName("GetLastTradePrice", "WOMBAT",
+ *                              "http://www.wombat.org/trader");
+ *  d.addDetailEntry(name);
+ *  Iterator<DetailEntry> it = d.getDetailEntries();
+ * }
  *
  * @since 1.6
  */

api/src/main/java/jakarta/xml/soap/FactoryFinder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -10,16 +10,11 @@
 
 package jakarta.xml.soap;
 
-import java.io.InputStream;
 import java.lang.reflect.Method;
 import java.net.URL;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.util.Iterator;
-import java.util.Properties;
 import java.util.logging.ConsoleHandler;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@@ -30,7 +25,7 @@ class FactoryFinder {
     private static final Logger logger;
 
     private static final ServiceLoaderUtil.ExceptionHandler<SOAPException> EXCEPTION_HANDLER =
-            new ServiceLoaderUtil.ExceptionHandler<SOAPException>() {
+            new ServiceLoaderUtil.ExceptionHandler<>() {
                 @Override
                 public SOAPException createException(Throwable throwable, String message) {
                     return new SOAPException(message, throwable);
@@ -152,15 +147,12 @@ private static Object newInstance(String className, String defaultClassName, Cla
 
     private static String fromSystemProperty(String factoryId) {
         String systemProp = getSystemProperty(factoryId);
-        if (systemProp != null) {
-            return systemProp;
-        }
-        return null;
+        return systemProp;
     }
 
     private static String getSystemProperty(final String property) {
         logger.log(Level.FINE, "Checking system property {0}", property);
-        String value = AccessController.doPrivileged(new PrivilegedAction<String>() {
+        String value = AccessController.doPrivileged(new PrivilegedAction<>() {
             @Override
             public String run() {
                 return System.getProperty(property);
@@ -218,9 +210,9 @@ private static <T> T lookupUsingOSGiServiceLoader(String factoryId) {
 
     /**
      * Get the URL for the Class from it's ClassLoader.
-     *
+     * <p>
      * Convenience method for {@link #which(Class, ClassLoader)}.
-     *
+     * <p>
      * Equivalent to calling: which(clazz, clazz.getClassLoader())
      *
      * @param clazz

api/src/main/java/jakarta/xml/soap/MessageFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -20,10 +20,10 @@
  * A SAAJ client can create a {@code MessageFactory} object
  * using the method {@code newInstance}, as shown in the following
  * lines of code.
- * <pre>{@code
- *       MessageFactory mf = MessageFactory.newInstance();
- *       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
- * }</pre>
+ * {@snippet :
+ *  MessageFactory mf = MessageFactory.newInstance();
+ *  MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
+ * }
  * <P>
  * All {@code MessageFactory} objects, regardless of how they are
  * created, will produce {@code SOAPMessage} objects that
@@ -35,7 +35,7 @@
  *  <LI>A {@code SOAPHeader} object
  * </UL>
  * In some cases, specialized MessageFactory objects may be obtained that produce messages
- * prepopulated with additional entries in the {@code SOAPHeader} object and the
+ * pre-populated with additional entries in the {@code SOAPHeader} object and the
  * {@code SOAPBody} object.
  * The content of a new {@code SOAPMessage} object depends on which of the two
  * {@code MessageFactory} methods is used to create it.
@@ -65,7 +65,7 @@ protected MessageFactory() {
     /**
      * Creates a new {@code MessageFactory} object that is an instance
      * of the default implementation (SOAP 1.1).
-     *
+     * <p>
      * This method uses the lookup procedure specified in {@link jakarta.xml.soap} to locate and load the
      * {@link jakarta.xml.soap.MessageFactory} class.
      *
@@ -104,7 +104,7 @@ public static MessageFactory newInstance() throws SOAPException {
      * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic
      * message factory creates messages based on the MIME headers specified
      * as arguments to the {@code createMessage} method.
-     *
+     * <p>
      * This method uses the SAAJMetaFactory to locate the implementation class
      * and create the MessageFactory instance.
      *
@@ -130,7 +130,7 @@ public static MessageFactory newInstance(String protocol) throws SOAPException {
      * Creates a new {@code SOAPMessage} object with the default
      * {@code SOAPPart}, {@code SOAPEnvelope}, {@code SOAPBody},
      * and {@code SOAPHeader} objects. Profile-specific message factories
-     * can choose to prepopulate the {@code SOAPMessage} object with
+     * can choose to pre-populate the {@code SOAPMessage} object with
      * profile-specific headers.
      * <P>
      * Content can be added to this message's {@code SOAPPart} object, and

api/src/main/java/jakarta/xml/soap/MimeHeaders.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -38,11 +38,11 @@ public MimeHeaders() {
     }
 
     /**
-     * Returns all of the values for the specified header as an array of
+     * Returns all the values for the specified header as an array of
      * {@code String} objects.
      *
      * @param   name the name of the header for which values will be returned
-     * @return a {@code String} array with all of the values for the
+     * @return a {@code String} array with all the values for the
      *         specified header
      * @see #setHeader
      */
@@ -56,10 +56,10 @@ public String[] getHeader(String name) {
                 values.addElement(hdr.getValue());
         }
 
-        if (values.size() == 0)
+        if (values.isEmpty())
             return null;
 
-        String r[] = new String[values.size()];
+        String[] r = new String[values.size()];
         values.copyInto(r);
         return r;
     }
@@ -84,7 +84,7 @@ public void setHeader(String name, String value)
     {
         boolean found = false;
 
-        if ((name == null) || name.equals(""))
+        if ((name == null) || name.isEmpty())
             throw new IllegalArgumentException("Illegal MimeHeader name");
 
         for(int i = 0; i < headers.size(); i++) {
@@ -120,7 +120,7 @@ public void setHeader(String name, String value)
      */
     public void addHeader(String name, String value)
     {
-        if ((name == null) || name.equals(""))
+        if ((name == null) || name.isEmpty())
             throw new IllegalArgumentException("Illegal MimeHeader name");
 
         int pos = headers.size();