5.0.1: added Javadoc

Author: biagio

README.MD

@@ -9,13 +9,13 @@ Attenzione: le versioni precedenti alla 5.0.0 sono state rilasciato con groupId
 <dependency>
 	<groupId>app.tozzi</groupId>
 	<artifactId>pec-parser</artifactId>
-	<version>5.0.0</version>
+	<version>5.0.1</version>
 </dependency>
 ```
 
 ##### Gradle
 ```
-implementation 'app.tozzi:pec-parser:5.0.0 
+implementation 'app.tozzi:pec-parser:5.0.1 
 ```
 
 ### Requisiti

build.gradle

@@ -6,7 +6,7 @@ plugins {
 }
 
 group = 'app.tozzi'
-version = '5.0.0'
+version = '5.0.1'
 
 java {
     sourceCompatibility = JavaVersion.VERSION_17
@@ -59,7 +59,7 @@ publishing {
         maven(MavenPublication) {
             group = 'app.tozzi'
             artifactId = 'pec-parser'
-            version = "5.0.0"
+            version = "5.0.1"
             from components.java
             pom {
                 name = 'pec-parser'

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

publiccode.yml

@@ -16,41 +16,39 @@ description:
         PEC e posta ordinaria
     genericName: PEC/Mail Parser
     longDescription: |
-      **PEC/Mail Parser
+      **PEC/Mail Parser**
 
-      **Libreria utility per l'elaborazione di messaggi di [Posta Elettronica
+      Libreria utility per l'elaborazione di messaggi di [Posta Elettronica
       Certificata](https://www.agid.gov.it/it/piattaforme/posta-elettronica-certificata)
       (PEC) e messaggi di posta ordinaria.
 
-
-
-      **Dipendenza progetto
-
-      **Attenzione: le versioni precedenti alla 5.0.0 sono state rilasciato con
+      **Dipendenza progetto**
+      Attenzione: le versioni precedenti alla 5.0.0 sono state rilasciato con
       groupId \`app.tozzi.mail\`
 
-
       _Maven_
 
       `<dependency>
+      
           <groupId>app.tozzi</groupId>
+      
           <artifactId>pec-parser</artifactId>
+      
           <version>5.0.0</version>
+      
       </dependency>`
 
 
       _Gradle_
 
-      `implementation 'app.tozzi:pec-parser:5.0.0 
-
-      `
+      `implementation 'app.tozzi:pec-parser:5.0.0`
 
       **Requisiti**
 
 
-      - [v0.0.1 - v4.0.0]: Java 8
+      - v0.0.1 - v4.0.0: Java 8
 
-      - [v5.0.0 - latest]: Java 17
+      - v5.0.0 - latest: Java 17
 
 
       ​
@@ -59,9 +57,9 @@ description:
 
       **Utilizzo**
 
-      ++1. Istanza di MailParser
+      1. Istanza di MailParser
 
-      ++Attraverso uno dei seguenti metodi:
+      Attraverso uno dei seguenti metodi:
 
 
       - `MailParser.getInstance()`
@@ -72,9 +70,9 @@ description:
 
       
 
-      ++2. Parsing
+      2. Parsing
 
-      ++Attraverso uno dei seguenti metodi:
+      Attraverso uno dei seguenti metodi:
 
       - `ParsedEntity parse(MimeMessage mimeMessage)`
 
@@ -85,9 +83,9 @@ description:
       - `ParsedEntity parse(MimeMessage mimeMessage)`
 
 
-      ++3. ParsedEntity
+      3. ParsedEntity
 
-      ++Può essere di tipo:
+      Può essere di tipo:
 
       - `PEC`: se il messaggio rappresenta una PEC
 
@@ -153,7 +151,7 @@ platforms:
   - linux
   - ios
   - android
-releaseDate: '2024-11-15'
+releaseDate: '2024-11-16'
 softwareType: standalone/web
-softwareVersion: 5.0.0
+softwareVersion: 5.0.1
 url: 'https://github.com/biagioT/java-pec-parser'

src/main/java/app/tozzi/MailParser.java

@@ -23,28 +23,72 @@
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
+/**
+ * Main core class that offers email/PEC extraction
+ *
+ * @author Biagio Tozzi
+ */
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class MailParser {
 
     private Properties properties;
     private boolean extractAllHeaders;
 
+    /**
+     * Default {@link MailParser} instance.
+     * <ul>
+     * <li>properties: System.getProperties(). System default properties</li>
+     * <li>extractAllHeaders: false. Not all additional headers will be extracted</li>
+     * </ul>
+     *
+     * @return {@link MailParser} instance
+     */
     public static MailParser getInstance() {
         return new MailParser(null, false);
     }
 
+    /**
+     * {@link MailParser} instance with custom properties
+     * <ul>
+     * <li>extractAllHeaders: false. Not all additional headers will be extracted</li>
+     * </ul>
+     *
+     * @return {@link MailParser} instance
+     */
     public static MailParser getInstance(Properties properties) {
         return new MailParser(properties, false);
     }
 
+    /**
+     * {@link MailParser} instance with the extraction of all the headers
+     *
+     * @return {@link MailParser} instance
+     */
     public static MailParser getInstance(boolean extractAllHeaders) {
         return new MailParser(null, extractAllHeaders);
     }
 
+    /**
+     * {@link MailParser} instance with the extraction of all the headers and custom properties
+     *
+     * @return {@link MailParser} instance
+     */
     public static MailParser getInstance(Properties properties, boolean extractAllHeaders) {
         return new MailParser(properties, extractAllHeaders);
     }
 
+    /**
+     * Extracts a {@link ParsedEntity} from a mail MIME message.<br>
+     * ParsedEntity can be:
+     * <ul>
+     * <li>{@link Mail}: simple mail</li>
+     * <li>{@link PEC}: Posta Elettronica Certificata - Italian certified electronic mail </li>
+     * <li>{@link PECReceipt}: Italian certified electronic mail receipt</li>
+     * </ul>
+     *
+     * @param mimeMessage {@link MimeMessage} mail MIME message
+     * @return {@link ParsedEntity}
+     */
     public ParsedEntity parse(MimeMessage mimeMessage) {
 
         var xTranspHeader = MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_TRASPORTO);
@@ -58,6 +102,18 @@ public ParsedEntity parse(MimeMessage mimeMessage) {
         return parsedEntity;
     }
 
+    /**
+     * Extracts a {@link ParsedEntity} from a mail message.<br>
+     * ParsedEntity can be:
+     * <ul>
+     * <li>{@link Mail}: simple mail</li>
+     * <li>{@link PEC}: Posta Elettronica Certificata - Italian certified electronic mail </li>
+     * <li>{@link PECReceipt}: Italian certified electronic mail receipt</li>
+     * </ul>
+     *
+     * @param eml {@link File} mail eml MIME message
+     * @return {@link ParsedEntity}
+     */
     public ParsedEntity parse(File eml) {
 
         if (eml == null || !eml.exists()) {
@@ -72,6 +128,18 @@ public ParsedEntity parse(File eml) {
         }
     }
 
+    /**
+     * Extracts a {@link ParsedEntity} from a mail message.<br>
+     * ParsedEntity can be:
+     * <ul>
+     * <li>{@link Mail}: simple mail</li>
+     * <li>{@link PEC}: Posta Elettronica Certificata - Italian certified electronic mail </li>
+     * <li>{@link PECReceipt}: Italian certified electronic mail receipt</li>
+     * </ul>
+     *
+     * @param eml {@link InputStream} eml mail mime message
+     * @return {@link ParsedEntity}
+     */
     public ParsedEntity parse(InputStream eml) {
         return parse(MimeMessageUtils.createMimeMessage(eml, properties));
     }
@@ -131,9 +199,9 @@ private static ParsedEntity extract(MimeMessage mimeMessage, boolean isPEC, bool
         return extractContent(mail, mimeMessage, isPEC, isPECReceipt, properties, extractAllHeaders);
     }
 
-    private static ParsedEntity extractContent(Mail mail, MimePart part, boolean isPEC, boolean isPECReceipt, Properties properties, boolean extractAllHeaders) {
+    private static ParsedEntity extractContent(Mail mail, MimeMessage mimeMessage, boolean isPEC, boolean isPECReceipt, Properties properties, boolean extractAllHeaders) {
         DataSourcePair<DataSource, DataSource> dsp = isPEC || isPECReceipt ? new DataSourcePair<>() : null;
-        extractContent(mail, part, isPEC, isPECReceipt, dsp);
+        extractContent(mail, mimeMessage, isPEC, isPECReceipt, dsp);
 
         if (isPEC || isPECReceipt) {
 
@@ -143,7 +211,7 @@ private static ParsedEntity extractContent(Mail mail, MimePart part, boolean isP
 
             try {
                 var postaCertMimeMessage = dsp.getElementA() != null ? MimeMessageUtils.createMimeMessage(dsp.getElementA().getInputStream(), properties) : null;
-                return PECHandler.loadPEC(postaCertMimeMessage != null ? (Mail) extract(postaCertMimeMessage, false, false, properties, extractAllHeaders) : null, mail, dsp.getElementA(), dsp.getElementB());
+                return PECHandler.loadPEC(postaCertMimeMessage != null ? (Mail) extract(postaCertMimeMessage, false, false, properties, extractAllHeaders) : null, mail, dsp.getElementA(), dsp.getElementB(), mimeMessage);
 
             } catch (IOException e) {
                 throw new MailParserException(e);

src/main/java/app/tozzi/core/DeliveryStatusHandler.java

@@ -8,8 +8,19 @@
 import java.io.BufferedReader;
 import java.io.InputStreamReader;
 
+/**
+ * Delivery Status management
+ *
+ * @author Biagio Tozzi
+ */
 public class DeliveryStatusHandler {
 
+    /**
+     * Extracts a {@link DeliveryStatus} object from {@link MimePart} part
+     *
+     * @param part
+     * @return {@link DeliveryStatus} object with delivery status info
+     */
     public static DeliveryStatus loadDeliveryStatus(MimePart part) {
 
         var deliveryStatus = new DeliveryStatus();

src/main/java/app/tozzi/core/PECHandler.java

@@ -5,9 +5,11 @@
 import app.tozzi.model.PEC;
 import app.tozzi.model.PECReceipt;
 import app.tozzi.model.exception.MailParserException;
+import app.tozzi.util.MimeMessageUtils;
 import app.tozzi.util.PECConstants;
 import app.tozzi.util.XMLUtils;
 import jakarta.activation.DataSource;
+import jakarta.mail.internet.MimeMessage;
 import org.xml.sax.SAXException;
 
 import javax.xml.parsers.DocumentBuilderFactory;
@@ -16,6 +18,11 @@
 import java.io.IOException;
 import java.io.InputStream;
 
+/**
+ * PEC Management
+ *
+ * @author Biagio Tozzi
+ */
 public class PECHandler {
 
     private static final DocumentBuilderFactory DOCUMENT_BUILDER_FACTORY;
@@ -24,6 +31,12 @@ public class PECHandler {
         DOCUMENT_BUILDER_FACTORY = DocumentBuilderFactory.newInstance();
     }
 
+    /**
+     * Extracts PEC receipt from {@link PEC}
+     *
+     * @param pec {@link PEC}
+     * @return {@link PECReceipt}
+     */
     public static PECReceipt loadReceipt(PEC pec) {
 
         try {
@@ -37,7 +50,16 @@ public static PECReceipt loadReceipt(PEC pec) {
         }
     }
 
-    public static PEC loadPEC(Mail originalMessage, Mail envelope, DataSource postaCert, DataSource datiCert) {
+    /**
+     * Extracts a {@link PEC}
+     *
+     * @param originalMessage original mail message
+     * @param envelope        PEC envelope
+     * @param postaCert       postaCert.eml stream
+     * @param datiCert        datiCert.xml stream
+     * @return {@link PEC}
+     */
+    public static PEC loadPEC(Mail originalMessage, Mail envelope, DataSource postaCert, DataSource datiCert, MimeMessage mimeMessage) {
 
         try {
             var pec = new PEC();
@@ -46,13 +68,29 @@ public static PEC loadPEC(Mail originalMessage, Mail envelope, DataSource postaC
             pec.setEnvelope(envelope);
             pec.setOriginalMessage(originalMessage);
             pec.setCertificateData(loadCertificateData(datiCert.getInputStream()));
+            pec.setTransportHeaderValue(MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_TRASPORTO));
+            pec.setReceiptHeaderValue(MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_RICEVUTA));
+            pec.setReceiptTypeHeaderValue(MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_TIPO_RICEVUTA));
+            pec.setSecurityCheckHeaderValue(MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_VERIFICA_SICUREZZA));
+            pec.setErrorHeaderValue(MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_TRASPORTO_ERRORE));
+            pec.setReferenceHeaderValue(MimeMessageUtils.getHeader(mimeMessage, PECConstants.X_RIFERIMENTO));
             return pec;
 
         } catch (Exception e) {
             throw new MailParserException("Error during PEC processing", e);
         }
     }
 
+    /**
+     * Extracts datiCert.xml
+     *
+     * @param inputStream datiCert.xml stream
+     * @return {@link CertificateData}
+     * @throws ParserConfigurationException
+     * @throws IOException
+     * @throws SAXException
+     * @throws XPathExpressionException
+     */
     static CertificateData loadCertificateData(InputStream inputStream) throws ParserConfigurationException, IOException, SAXException, XPathExpressionException {
         var document = DOCUMENT_BUILDER_FACTORY.newDocumentBuilder().parse(inputStream);
         var certificateData = new CertificateData();

src/main/java/app/tozzi/model/Address.java

@@ -3,6 +3,11 @@
 import lombok.Builder;
 import lombok.Data;
 
+/**
+ * Mail/PEC Address
+ *
+ * @author Biagio Tozzi
+ */
 @Data
 @Builder
 public class Address {