From fd4f288870d4afbdfe0cbea11bd74b953da1c807 Mon Sep 17 00:00:00 2001 From: Lukas Jungmann Date: Sat, 17 Feb 2024 20:50:25 +0100 Subject: [PATCH] Use snippet in javadoc, fix typos, grammar Signed-off-by: Lukas Jungmann --- .github/workflows/maven.yml | 2 +- api/README.md | 6 +- .../java/jakarta/xml/soap/AttachmentPart.java | 64 ++++++++-------- .../main/java/jakarta/xml/soap/Detail.java | 16 ++-- .../java/jakarta/xml/soap/FactoryFinder.java | 20 ++--- .../java/jakarta/xml/soap/MessageFactory.java | 18 ++--- .../java/jakarta/xml/soap/MimeHeaders.java | 14 ++-- api/src/main/java/jakarta/xml/soap/Name.java | 16 ++-- .../jakarta/xml/soap/SAAJMetaFactory.java | 4 +- .../java/jakarta/xml/soap/SAAJResult.java | 4 +- .../main/java/jakarta/xml/soap/SOAPBody.java | 4 +- .../jakarta/xml/soap/SOAPBodyElement.java | 8 +- .../java/jakarta/xml/soap/SOAPConnection.java | 12 ++- .../xml/soap/SOAPConnectionFactory.java | 4 +- .../java/jakarta/xml/soap/SOAPElement.java | 6 +- .../java/jakarta/xml/soap/SOAPEnvelope.java | 46 ++++++------ .../java/jakarta/xml/soap/SOAPFactory.java | 6 +- .../main/java/jakarta/xml/soap/SOAPFault.java | 74 +++++++++---------- .../java/jakarta/xml/soap/SOAPHeader.java | 24 +++--- .../jakarta/xml/soap/SOAPHeaderElement.java | 4 +- .../java/jakarta/xml/soap/SOAPMessage.java | 14 ++-- .../main/java/jakarta/xml/soap/SOAPPart.java | 18 ++--- .../jakarta/xml/soap/ServiceLoaderUtil.java | 6 +- .../java/jakarta/xml/soap/package-info.java | 4 +- .../xml/soap/test/SAAJFactoryTest.java | 13 ++-- 25 files changed, 198 insertions(+), 209 deletions(-) diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml index 61d2cfd..8c986e0 100644 --- a/.github/workflows/maven.yml +++ b/.github/workflows/maven.yml @@ -23,7 +23,7 @@ jobs: strategy: matrix: - java_version: [ 17, 21 ] + java_version: [ 21 ] steps: - name: Checkout for build diff --git a/api/README.md b/api/README.md index 51bb9a0..9bae980 100644 --- a/api/README.md +++ b/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: diff --git a/api/src/main/java/jakarta/xml/soap/AttachmentPart.java b/api/src/main/java/jakarta/xml/soap/AttachmentPart.java index 03e39ea..b1b0c8f 100644 --- a/api/src/main/java/jakarta/xml/soap/AttachmentPart.java +++ b/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: - * 
- *       Content-Type:  application/xml
- *
+ * {@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. - * 
- *       ap.setMimeHeader("Content-Type", "application/xml");
- *
+ * {@snippet : + * ap.setMimeHeader("Content-Type", "application/xml"); + * } * * *

@@ -58,28 +58,28 @@ * *

* 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. - * 

- *     AttachmentPart ap1 = m.createAttachmentPart();
- *     ap1.setContent(contentString1, "text/plain");
- *     m.addAttachmentPart(ap1);
- *
+ * {@snippet : + * AttachmentPart ap1 = m.createAttachmentPart(); + * ap1.setContent(contentString1, "text/plain"); + * m.addAttachmentPart(ap1); + * } * * *

* 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. - * 

- *     AttachmentPart ap2 = m.createAttachmentPart();
- *     byte[] jpegData =  ...;
- *     ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
- *     m.addAttachmentPart(ap2);
- *
+ * {@snippet : + * AttachmentPart ap2 = m.createAttachmentPart(); + * byte[] jpegData = ...; + * ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg"); + * m.addAttachmentPart(ap2); + * } *

* The {@code getContent} method retrieves the contents and header from * an {@code AttachmentPart} object. Depending on the @@ -87,16 +87,16 @@ * {@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. - * 

- *     String content1 = ap1.getContent();
- *     java.io.InputStream content2 = ap2.getContent();
- *
+ * {@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. - * 
- *     ap1.clearContent();
- *
+ * {@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 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 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. diff --git a/api/src/main/java/jakarta/xml/soap/Detail.java b/api/src/main/java/jakarta/xml/soap/Detail.java index 84a1961..a432bcd 100644 --- a/api/src/main/java/jakarta/xml/soap/Detail.java +++ b/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 se, used to create the {@code Name} object, * is a {@code SOAPEnvelope} object. - * 
{@code
- *    Detail d = sf.getDetail();
- *    Name name = se.createName("GetLastTradePrice", "WOMBAT",
- *                                "http://www.wombat.org/trader");
- *    d.addDetailEntry(name);
- *    Iterator it = d.getDetailEntries();
- * }
+ * {@snippet : + * Detail d = sf.getDetail(); + * Name name = se.createName("GetLastTradePrice", "WOMBAT", + * "http://www.wombat.org/trader"); + * d.addDetailEntry(name); + * Iterator it = d.getDetailEntries(); + * } * * @since 1.6 */ diff --git a/api/src/main/java/jakarta/xml/soap/FactoryFinder.java b/api/src/main/java/jakarta/xml/soap/FactoryFinder.java index fab5d37..47c4d5f 100644 --- a/api/src/main/java/jakarta/xml/soap/FactoryFinder.java +++ b/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 EXCEPTION_HANDLER = - new ServiceLoaderUtil.ExceptionHandler() { + 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 value = AccessController.doPrivileged(new PrivilegedAction<>() { @Override public String run() { return System.getProperty(property); @@ -218,9 +210,9 @@ private static T lookupUsingOSGiServiceLoader(String factoryId) { /** * Get the URL for the Class from it's ClassLoader. - * + *

* Convenience method for {@link #which(Class, ClassLoader)}. - * + *

* Equivalent to calling: which(clazz, clazz.getClassLoader()) * * @param clazz diff --git a/api/src/main/java/jakarta/xml/soap/MessageFactory.java b/api/src/main/java/jakarta/xml/soap/MessageFactory.java index dee50cf..7ed7da5 100644 --- a/api/src/main/java/jakarta/xml/soap/MessageFactory.java +++ b/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. - * 

{@code
- *       MessageFactory mf = MessageFactory.newInstance();
- *       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
- * }
+ * {@snippet : + * MessageFactory mf = MessageFactory.newInstance(); + * MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL); + * } *

* All {@code MessageFactory} objects, regardless of how they are * created, will produce {@code SOAPMessage} objects that @@ -35,7 +35,7 @@ *

  • A {@code SOAPHeader} object * * 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). - * + *

    * 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. - * + *

    * 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. *

    * Content can be added to this message's {@code SOAPPart} object, and diff --git a/api/src/main/java/jakarta/xml/soap/MimeHeaders.java b/api/src/main/java/jakarta/xml/soap/MimeHeaders.java index 7f17796..5b45818 100644 --- a/api/src/main/java/jakarta/xml/soap/MimeHeaders.java +++ b/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(); diff --git a/api/src/main/java/jakarta/xml/soap/Name.java b/api/src/main/java/jakarta/xml/soap/Name.java index 7fac67e..b64e859 100644 --- a/api/src/main/java/jakarta/xml/soap/Name.java +++ b/api/src/main/java/jakarta/xml/soap/Name.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 @@ -40,17 +40,17 @@ * The following line of * code, in which se is a {@code SOAPEnvelope} object, creates a new * {@code Name} object with all three. - * 

    {@code
- *     Name name = se.createName("GetLastTradePrice", "WOMBAT",
- *                                "http://www.wombat.org/trader");
- * }
    + * {@snippet : + * Name name = se.createName("GetLastTradePrice", "WOMBAT", + * "http://www.wombat.org/trader"); + * } * The following line of code gives an example of how a {@code Name} object * can be used. The variable element is a {@code SOAPElement} object. * This code creates a new {@code SOAPElement} object with the given name and * adds it to element. - * 
    {@code
- *     element.addChildElement(name);
- * }
    + * {@snippet : + * element.addChildElement(name); + * } *

    * The {@code Name} interface may be deprecated in a future release of SAAJ * in favor of {@code javax.xml.namespace.QName} diff --git a/api/src/main/java/jakarta/xml/soap/SAAJMetaFactory.java b/api/src/main/java/jakarta/xml/soap/SAAJMetaFactory.java index 5ae95c0..e8f56ba 100644 --- a/api/src/main/java/jakarta/xml/soap/SAAJMetaFactory.java +++ b/api/src/main/java/jakarta/xml/soap/SAAJMetaFactory.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 @@ -54,7 +54,7 @@ public abstract class SAAJMetaFactory { * single place. Changing out the SAAJMetaFactory has the effect of changing out the entire SAAJ * implementation. Service providers provide the name of their {@code SAAJMetaFactory} * implementation. - * + *

    * This method uses the lookup procedure specified in {@link jakarta.xml.soap} to locate and load the * {@link jakarta.xml.soap.SAAJMetaFactory} class. * diff --git a/api/src/main/java/jakarta/xml/soap/SAAJResult.java b/api/src/main/java/jakarta/xml/soap/SAAJResult.java index fb88f7f..1e05b6f 100644 --- a/api/src/main/java/jakarta/xml/soap/SAAJResult.java +++ b/api/src/main/java/jakarta/xml/soap/SAAJResult.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2004, 2023 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 @@ -75,7 +75,7 @@ public SAAJResult(String protocol) throws SOAPException { * {@code SOAPPart} of the supplied {@code SOAPMessage}. * In the normal case these results will be written using DOM APIs and, * as a result, the finished {@code SOAPPart} will not be guaranteed - * to be well-formed unless the data used to create it is also well formed. + * to be well-formed unless the data used to create it is also well-formed. * When used in a transformation the validity of the {@code SOAPMessage} * after the transformation can be guaranteed only by means outside SAAJ * specification. diff --git a/api/src/main/java/jakarta/xml/soap/SOAPBody.java b/api/src/main/java/jakarta/xml/soap/SOAPBody.java index a15ecf0..f1c3149 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPBody.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPBody.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 @@ -12,8 +12,6 @@ import java.util.Locale; -import org.w3c.dom.Document; - import javax.xml.namespace.QName; /** diff --git a/api/src/main/java/jakarta/xml/soap/SOAPBodyElement.java b/api/src/main/java/jakarta/xml/soap/SOAPBodyElement.java index eb804e3..4bf08c0 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPBodyElement.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPBodyElement.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 @@ -20,9 +20,9 @@ * method {@code addBodyElement}. In the following line of code, * {@code sb} is a {@code SOAPBody} object, and * {@code myName} is a {@code Name} object. - * 

    {@code
- *    SOAPBodyElement sbe = sb.addBodyElement(myName);
- * }
    + * {@snippet : + * SOAPBodyElement sbe = sb.addBodyElement(myName); + * } * * @since 1.6 */ diff --git a/api/src/main/java/jakarta/xml/soap/SOAPConnection.java b/api/src/main/java/jakarta/xml/soap/SOAPConnection.java index 82c1251..87cc1cd 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPConnection.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPConnection.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 @@ -11,8 +11,6 @@ package jakarta.xml.soap; -import java.net.URLConnection; - /** * A point-to-point connection that a client can use for sending messages * directly to a remote party (represented by a URL, for instance). @@ -24,10 +22,10 @@ *

    * A client can obtain a {@code SOAPConnection} object using a * {@link SOAPConnectionFactory} object as in the following example: - * 

    {@code
- *      SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
- *      SOAPConnection con = factory.createConnection();
- * }
    + * {@snippet : + * SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance(); + * SOAPConnection con = factory.createConnection(); + * } * A {@code SOAPConnection} object can be used to send messages * directly to a URL following the request/response paradigm. That is, * messages are sent using the method {@code call}, which sends the diff --git a/api/src/main/java/jakarta/xml/soap/SOAPConnectionFactory.java b/api/src/main/java/jakarta/xml/soap/SOAPConnectionFactory.java index c91a9fe..566e8af 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPConnectionFactory.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPConnectionFactory.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 @@ -38,7 +38,7 @@ protected SOAPConnectionFactory() { /** * Creates an instance of the default * {@code SOAPConnectionFactory} object. - * + *

    * This method uses the lookup procedure specified in {@link jakarta.xml.soap} to locate and load the * {@link jakarta.xml.soap.SOAPConnectionFactory} class. * diff --git a/api/src/main/java/jakarta/xml/soap/SOAPElement.java b/api/src/main/java/jakarta/xml/soap/SOAPElement.java index 2677232..c875403 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPElement.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPElement.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 @@ -252,7 +252,7 @@ SOAPElement addNamespaceDeclaration(String prefix, String uri) String getAttributeValue(QName qname); /** - * Returns an {@code Iterator} over all of the attribute + * Returns an {@code Iterator} over all the attribute * {@code Name} objects in this * {@code SOAPElement} object. The iterator can be used to get * the attribute names, which can then be passed to the method @@ -265,7 +265,7 @@ SOAPElement addNamespaceDeclaration(String prefix, String uri) Iterator getAllAttributes(); /** - * Returns an {@code Iterator} over all of the attributes + * Returns an {@code Iterator} over all the attributes * in this {@code SOAPElement} as {@code QName} objects. * The iterator can be used to get the attribute QName, which can then * be passed to the method {@code getAttributeValue} to retrieve diff --git a/api/src/main/java/jakarta/xml/soap/SOAPEnvelope.java b/api/src/main/java/jakarta/xml/soap/SOAPEnvelope.java index 50ba219..f6d768d 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPEnvelope.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPEnvelope.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 @@ -31,12 +31,12 @@ * object message to get the {@code SOAPPart} object sp, * which is then used to get the {@code SOAPEnvelope} object se. * - * 

    {@code
- *     SOAPPart sp = message.getSOAPPart();
- *     SOAPEnvelope se = sp.getEnvelope();
- *     SOAPHeader sh = se.getHeader();
- *     SOAPBody sb = se.getBody();
- * }
    + * {@snippet : + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * SOAPHeader sh = se.getHeader(); + * SOAPBody sb = se.getBody(); + * } *

    * It is possible to change the body or header of a {@code SOAPEnvelope} * object by retrieving the current one, deleting it, and then adding @@ -44,9 +44,9 @@ * {@code detachNode} deletes the XML element (node) on which it is * called. For example, the following line of code deletes the * {@code SOAPBody} object that is retrieved by the method {@code getBody}. - * 

    {@code
- *      se.getBody().detachNode();
- * }
    + * {@snippet : + * se.getBody().detachNode(); + * } * To create a {@code SOAPHeader} object to replace the one that was removed, * a client uses * the method {@code SOAPEnvelope.addHeader}, which creates a new header and @@ -56,28 +56,28 @@ * retrieves the current header, removes it, and adds a new one. Then * it retrieves the current body, removes it, and adds a new one. * - * 
    {@code
- *     SOAPPart sp = message.getSOAPPart();
- *     SOAPEnvelope se = sp.getEnvelope();
- *     se.getHeader().detachNode();
- *     SOAPHeader sh = se.addHeader();
- *     se.getBody().detachNode();
- *     SOAPBody sb = se.addBody();
- * }
    + * {@snippet : + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * se.getHeader().detachNode(); + * SOAPHeader sh = se.addHeader(); + * se.getBody().detachNode(); + * SOAPBody sb = se.addBody(); + * } * It is an error to add a {@code SOAPBody} or {@code SOAPHeader} * object if one already exists. *

    * The {@code SOAPEnvelope} interface provides three methods for creating * {@code Name} objects. One method creates {@code Name} objects with - * a local name, a namespace prefix, and a namesapce URI. The second method creates + * a local name, a namespace prefix, and a namespace URI. The second method creates * {@code Name} objects with a local name and a namespace prefix, and the third * creates {@code Name} objects with just a local name. The following line of * code, in which se is a {@code SOAPEnvelope} object, creates a new * {@code Name} object with all three. - * 

    {@code
- *     Name name = se.createName("GetLastTradePrice", "WOMBAT",
- *                                "http://www.wombat.org/trader");
- * }
    + * {@snippet : + * Name name = se.createName("GetLastTradePrice", "WOMBAT", + * "http://www.wombat.org/trader"); + * } * * @since 1.6 */ diff --git a/api/src/main/java/jakarta/xml/soap/SOAPFactory.java b/api/src/main/java/jakarta/xml/soap/SOAPFactory.java index 0df92a4..cf86f08 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPFactory.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPFactory.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 @@ -17,13 +17,13 @@ /** * {@code SOAPFactory} is a factory for creating various objects * that exist in the SOAP XML tree. - + *

    * {@code SOAPFactory} can be * used to create XML fragments that will eventually end up in the * SOAP part. These fragments can be inserted as children of the * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or * {@link SOAPEnvelope} or other {@link SOAPElement} objects. - * + *

    * {@code SOAPFactory} also has methods to create * {@code jakarta.xml.soap.Detail} objects as well as * {@code java.xml.soap.Name} objects. diff --git a/api/src/main/java/jakarta/xml/soap/SOAPFault.java b/api/src/main/java/jakarta/xml/soap/SOAPFault.java index 1243a92..7b582ac 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPFault.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPFault.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 @@ -40,16 +40,16 @@ public interface SOAPFault extends SOAPBodyElement { * be of type {@code Name}. This method provides a convenient * way to set a fault code. For example, * - * 

    {@code
-     * SOAPEnvelope se = ...;
-     * // Create a qualified name in the SOAP namespace with a localName
-     * // of "Client". Note that prefix parameter is optional and is null
-     * // here which causes the implementation to use an appropriate prefix.
-     * Name qname = se.createName("Client", null,
-     *                            SOAPConstants.URI_NS_SOAP_ENVELOPE);
-     * SOAPFault fault = ...;
-     * fault.setFaultCode(qname);
-     * }
    + * {@snippet : + * SOAPEnvelope se = ...; + * // Create a qualified name in the SOAP namespace with a localName + * // of "Client". Note that prefix parameter is optional and is null + * // here which causes the implementation to use an appropriate prefix. + * Name qname = se.createName("Client", null, + * SOAPConstants.URI_NS_SOAP_ENVELOPE); + * SOAPFault fault = ...; + * fault.setFaultCode(qname); + * } * It is preferable to use this method over {@link #setFaultCode(String)}. * * @param faultCodeQName a {@code Name} object giving the fault @@ -65,7 +65,7 @@ public interface SOAPFault extends SOAPBodyElement { /** * Sets this {@code SOAPFault} object with the given fault code. - * + *

    * It is preferable to use this method over {@link #setFaultCode(Name)}. * * @param faultCodeQName a {@code QName} object giving the fault @@ -224,9 +224,9 @@ public interface SOAPFault extends SOAPBodyElement { * If this * {@code SOAPFault} is part of a message that supports SOAP 1.2 then * this call is equivalent to: - * 

    {@code
-     *      addFaultReasonText(faultString, Locale.getDefault());
-     * }
    + * {@snippet : + * addFaultReasonText(faultString, Locale.getDefault()); + * } * * @param faultString a {@code String} giving an explanation of * the fault @@ -244,9 +244,9 @@ public interface SOAPFault extends SOAPBodyElement { * If this * {@code SOAPFault} is part of a message that supports SOAP 1.2 then * this call is equivalent to: - * 
    {@code
-     *      addFaultReasonText(faultString, locale);
-     * }
    + * {@snippet : + * addFaultReasonText(faultString, locale); + * } * * @param faultString a {@code String} giving an explanation of * the fault @@ -268,13 +268,13 @@ void setFaultString(String faultString, Locale locale) * If this * {@code SOAPFault} is part of a message that supports SOAP 1.2 then * this call is equivalent to: - * 
    {@code
-     *    String reason = null;
-     *    try {
-     *        reason = (String) getFaultReasonTexts().next();
-     *    } catch (SOAPException e) {}
-     *    return reason;
-     * }
    + * {@snippet : + * String reason = null; + * try { + * reason = (String) getFaultReasonTexts().next(); + * } catch (SOAPException e) {} + * return reason; + * } * * @return a {@code String} giving an explanation of * the fault @@ -290,13 +290,13 @@ void setFaultString(String faultString, Locale locale) * If this * {@code SOAPFault} is part of a message that supports SOAP 1.2 then * this call is equivalent to: - * 
    {@code
-     *    Locale locale = null;
-     *    try {
-     *        locale = (Locale) getFaultReasonLocales().next();
-     *    } catch (SOAPException e) {}
-     *    return locale;
-     * }
    + * {@snippet : + * Locale locale = null; + * try { + * locale = (Locale) getFaultReasonLocales().next(); + * } catch (SOAPException e) {} + * return locale; + * } * * @return a {@code Locale} object indicating the native language of * the fault string or {@code null} if no locale was specified @@ -370,7 +370,7 @@ void setFaultString(String faultString, Locale locale) /** * Returns an {@code Iterator} over a sequence of - * {@code String} objects containing all of the Reason Text items for + * {@code String} objects containing all the Reason Text items for * this {@code SOAPFault}. * * @return an {@code Iterator} over env:Fault/env:Reason/env:Text items. @@ -415,10 +415,10 @@ void setFaultString(String faultString, Locale locale) *

    * Code sample: * - * 

    {@code
-     * SOAPFault fault = ...;
-     * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
-     * }
    + * {@snippet : + * SOAPFault fault = ...; + * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH); + * } * * @param text -- reason message string * @param locale -- Locale object representing the locale of the message diff --git a/api/src/main/java/jakarta/xml/soap/SOAPHeader.java b/api/src/main/java/jakarta/xml/soap/SOAPHeader.java index 4c14bf1..b9c0cd3 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPHeader.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPHeader.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 @@ -27,18 +27,18 @@ * object, which is optional, is not needed, it can be retrieved and deleted * with the following line of code. The variable se is a * {@code SOAPEnvelope} object. - * 
    {@code
- *      se.getHeader().detachNode();
- * }
    + * {@snippet : + * se.getHeader().detachNode(); + * } * * A {@code SOAPHeader} object is created with the {@code SOAPEnvelope} * method {@code addHeader}. This method, which creates a new header and adds it * to the envelope, may be called only after the existing header has been removed. * - * 
    {@code
- *      se.getHeader().detachNode();
- *      SOAPHeader sh = se.addHeader();
- * }
    + * {@snippet : + * se.getHeader().detachNode(); + * SOAPHeader sh = se.addHeader(); + * } *

    * A {@code SOAPHeader} object can have only {@code SOAPHeaderElement} * objects as its immediate children. The method {@code addHeaderElement} @@ -46,9 +46,9 @@ * {@code SOAPHeader} object. In the following line of code, the * argument to the method {@code addHeaderElement} is a {@code Name} * object that is the name for the new {@code HeaderElement} object. - * 

    {@code
- *      SOAPHeaderElement shElement = sh.addHeaderElement(name);
- * }
    + * {@snippet : + * SOAPHeaderElement shElement = sh.addHeaderElement(name); + * } * * @see SOAPHeaderElement * @since 1.6 @@ -109,7 +109,7 @@ SOAPHeaderElement addHeaderElement(QName qname) * Returns an {@code Iterator} over all the {@code SOAPHeaderElement} objects * in this {@code SOAPHeader} object * that have the specified actor. - * + *

    * An actor is a global attribute that indicates the intermediate * parties that should process a message before it reaches its ultimate * receiver. An actor receives the message and processes it before sending diff --git a/api/src/main/java/jakarta/xml/soap/SOAPHeaderElement.java b/api/src/main/java/jakarta/xml/soap/SOAPHeaderElement.java index e135333..e0b3d40 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPHeaderElement.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPHeaderElement.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 @@ -117,7 +117,7 @@ public interface SOAPHeaderElement extends SOAPElement { * block must be relayed by any node that is targeted by the header block * but not actually process it. This attribute is ignored on header blocks * whose mustUnderstand attribute is set to true or that are targeted at - * the ultimate reciever (which is the default). The default value of this + * the ultimate receiver (which is the default). The default value of this * attribute is {@code false}. * * @param relay the new value of the relay attribute diff --git a/api/src/main/java/jakarta/xml/soap/SOAPMessage.java b/api/src/main/java/jakarta/xml/soap/SOAPMessage.java index 513fe9f..01642e0 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPMessage.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPMessage.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 @@ -41,12 +41,12 @@ * object, and the {@code SOAPEnvelope} object is used to retrieve the * {@code SOAPBody} and {@code SOAPHeader} objects. * - * 

    {@code
- *     SOAPPart sp = message.getSOAPPart();
- *     SOAPEnvelope se = sp.getEnvelope();
- *     SOAPBody sb = se.getBody();
- *     SOAPHeader sh = se.getHeader();
- * }
    + * {@snippet : + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * SOAPBody sb = se.getBody(); + * SOAPHeader sh = se.getHeader(); + * } * *

    * In addition to the mandatory {@code SOAPPart} object, a {@code SOAPMessage} diff --git a/api/src/main/java/jakarta/xml/soap/SOAPPart.java b/api/src/main/java/jakarta/xml/soap/SOAPPart.java index b7f3517..9854427 100644 --- a/api/src/main/java/jakarta/xml/soap/SOAPPart.java +++ b/api/src/main/java/jakarta/xml/soap/SOAPPart.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 @@ -39,9 +39,9 @@ * calling the method {@code SOAPMessage.getSOAPPart}. The * following line of code, in which {@code message} is a * {@code SOAPMessage} object, retrieves the SOAP part of a message. - * 

    {@code
- *   SOAPPart soapPart = message.getSOAPPart();
- * }
    + * {@snippet : + * SOAPPart soapPart = message.getSOAPPart(); + * } *

    * A {@code SOAPPart} object contains a {@code SOAPEnvelope} object, * which in turn contains a {@code SOAPBody} object and a @@ -161,7 +161,7 @@ public void setContentLocation(String contentLocation) * existing header is a match. If there is a match, this method clears * all existing values for the first header that matches and sets the * given value instead. If more than one header has - * the given name, this method removes all of the matching headers after + * the given name, this method removes all the matching headers after * the first one. *

    * Note that RFC822 headers can contain only US-ASCII characters. @@ -201,7 +201,7 @@ public void setContentLocation(String contentLocation) * Retrieves all the headers for this {@code SOAPPart} 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 SOAPPart} object */ public abstract Iterator getAllMimeHeaders(); @@ -212,7 +212,7 @@ public void setContentLocation(String contentLocation) * * @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, returned as an {@code Iterator} object */ public abstract Iterator getMatchingMimeHeaders(String[] names); @@ -223,9 +223,9 @@ public void setContentLocation(String contentLocation) * * @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 SOAPPart} object + * @return all the MIME headers in this {@code SOAPPart} object * except those that match one of the names in the - * given array. The nonmatching MIME headers are returned as an + * given array. The non-matching MIME headers are returned as an * {@code Iterator} object. */ public abstract Iterator getNonMatchingMimeHeaders(String[] names); diff --git a/api/src/main/java/jakarta/xml/soap/ServiceLoaderUtil.java b/api/src/main/java/jakarta/xml/soap/ServiceLoaderUtil.java index dd46417..03e7964 100644 --- a/api/src/main/java/jakarta/xml/soap/ServiceLoaderUtil.java +++ b/api/src/main/java/jakarta/xml/soap/ServiceLoaderUtil.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2022 Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 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 @@ -15,7 +15,7 @@ import java.util.logging.Logger; /** - * Shared ServiceLoader/FactoryFinder Utils shared among SAAJ, JAXB and JAXWS + * Shared ServiceLoader/FactoryFinder Utils shared among SAAJ, XML-Binding and XML-WS. * Class duplicated to all those projects. * * @author Miroslav.Kos@oracle.com @@ -42,7 +42,7 @@ static P firstByServiceLoader(Class

    spiClass, } static void checkPackageAccess(String className) { - // make sure that the current thread has an access to the package of the given name. + // make sure that the current thread has the access to the package of the given name. SecurityManager s = System.getSecurityManager(); if (s != null) { int i = className.lastIndexOf('.'); diff --git a/api/src/main/java/jakarta/xml/soap/package-info.java b/api/src/main/java/jakarta/xml/soap/package-info.java index 3a3a84b..3a06853 100644 --- a/api/src/main/java/jakarta/xml/soap/package-info.java +++ b/api/src/main/java/jakarta/xml/soap/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2022 Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 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 @@ -32,7 +32,7 @@ * References in this document to JAXB refer to the Jakarta XML Binding unless otherwise noted. * *

    - * In addition the APIs in the jakarta.xml.soap package extend + * In addition, the APIs in the jakarta.xml.soap package extend * their counterparts in the org.w3c.dom package. This means that * the SOAPPart of a SOAPMessage is also a DOM Level * 2 Document, and can be manipulated as such by applications, diff --git a/api/src/test/java/jakarta/xml/soap/test/SAAJFactoryTest.java b/api/src/test/java/jakarta/xml/soap/test/SAAJFactoryTest.java index ffc3cb1..3d132fc 100644 --- a/api/src/test/java/jakarta/xml/soap/test/SAAJFactoryTest.java +++ b/api/src/test/java/jakarta/xml/soap/test/SAAJFactoryTest.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016, 2022 Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2016, 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 @@ -26,10 +26,12 @@ import java.util.logging.Logger; import jakarta.xml.soap.MessageFactory; +import static junit.framework.TestCase.assertEquals; +import static junit.framework.TestCase.assertNotNull; import static junit.framework.TestCase.assertTrue; /* - * test for JDK-8131334: SAAJ Plugability Layer: using java.util.ServiceLoader + * test for JDK-8131334: SAAJ Pluggability Layer: using java.util.ServiceLoader */ @RunWith(Parameterized.class) public class SAAJFactoryTest { @@ -62,7 +64,7 @@ public class SAAJFactoryTest { @Parameterized.Parameters public static Collection configurations() { return Arrays.asList(new Object[][]{ - // see SAAJFactoryTest constructor signature for paremeters meaning ... + // see SAAJFactoryTest constructor signature for parameters meaning ... {null, "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl", jakarta.xml.soap.SOAPException.class, "scenario2", null}, {"saaj.factory.Valid", "saaj.factory.Valid", null, "scenario5", null}, {"saaj.factory.NonExisting SAAJFactoryTest", null, jakarta.xml.soap.SOAPException.class, "scenario6", null}, @@ -103,10 +105,9 @@ public void testFactoryDiscovery() throws IOException { logConfigurations(); try { MessageFactory factory = factory(); - assertTrue("No factory found.", factory != null); + assertNotNull("No factory found.", factory); String className = factory.getClass().getName(); - assertTrue("Incorrect factory: [" + className + "], Expected: [" + expectedFactory + "]", - expectedFactory.equals(className)); + assertEquals("Incorrect factory: [" + className + "], Expected: [" + expectedFactory + "]", expectedFactory, className); } catch (Throwable throwable) { Class throwableClass = throwable.getClass();