Añade referencias a .getResourceAsStream()

Author: sio2sio2

source/01.archivos/01.gestion.rst

@@ -253,6 +253,59 @@ podemos hacer construcciones como esta:
       [#]_ y crear código condicional que implemente la solución dependiendo
       cuál sea.
 
+.. _file-arc-pro:
+
+Archivos del proyecto
+---------------------
+Es común que, cuando desarrollamos una aplicación, tengamos que hacer referencia
+a archivos que hemos incluido dentro de ella. Un error de principiante es hacer
+lo siguiente:
+
+.. code-block:: java
+
+   // No haga esto jamás.
+   Path path = Path.of(System.getProperty("user.dir"), "imagen.jpg");
+
+Durante el desarrollo, si colocamos el archivo de imagen en el directorio de
+proyecto, la aplicación posiblemente encontrará el archivo, porque el |IDE|
+suele fijar el *directorio de proyecto* (que es lo que significa realmente
+``user.dir``) como *directorio de trabajo*. Sin embargo, al empaquetarla en
+un archivo |JAR|, no lo hará porque el archivo se encontrará dentro del paquete
+y el directorio de trabajo será el directorio desde el que el usuario ejecuta la
+aplicación.
+
+La forma correcta de acceder a archivos para su lectura incluidos en la
+aplicación es:
+
+.. code-block:: java
+
+   // Obsérvese la ruta absoluta.
+   InputStream st = getClass().getResourceAsStream("/imagen.jpg");
+
+que abre el archivo como un |InputStream| para su lectura y entiende que el
+archivo está en la raíz del *classpath*. Ya veremos más adelante :ref:`cómo
+utilizar estos flujos <iotext-r>`.
+
+.. note:: Hemos supuesto que la línea está dentro de un método de instancia. Si
+   fuera estático, tendríamos que utilizar directamente la clase:
+
+   .. code-block:: java
+
+      InputStream st = Main.class.getResourceAsStream("/imagen.jpg");
+
+Cuando la ruta es relativa, en vez de absoluta, se entiende que es referida
+al directorio del *classpath* donde se encuentra la clase que se utiliza para
+invocar el método.
+
+.. caution:: En los proyectos de *Java* suele existir un directorio
+   :file:`resources` para almacenar archivos con datos. El contenido de este
+   directorio acaba en la aplicación en la raíz del *classpath*. Por tanto, el
+   archivo de imagen que hemos puesto de ejemplo, podríamos hacerlo incluido en
+   este subdirectorio del proyecto. Ahora bien, con :ref:`Maven` la copia a
+   *classpath* no es automática y hay que declararla en :file:`pom.xml`. Vea un
+   ejemplo de :ref:`cómo añadir archivos con propiedades <add-resources>` en uno
+   de los apéndices.
+
 .. _file.files:
 
 Gestión
@@ -397,3 +450,7 @@ contenido, pero los dejamos para el siguiente epígrafe.
 .. |API| replace:: :abbr:`API (Application Programming Interface)`
 .. |MIME| replace:: :abbr:`MIME (Multipurpose Internet Mail Extensions)`
 .. |URI| replace:: :abbr:`URI (Uniform Resource Identifier)`
+.. |IDE| replace:: :abbr:`IDE (Integrated Development Environment)`
+.. |JAR| replace:: :abbr:`JAR (Java ARchive)`
+.. |InputStream| replace:: :java-io:`InputStream <InputStream>`
+

source/01.archivos/02.manipulacion.rst

@@ -80,6 +80,25 @@ y que también coincide con el tipo de ``System.in``:
 
    InputStream st = System.in;
 
+Un caso particular son los archivos que se incluyen dentro de la aplicación,
+que pueden leerse con:
+
+.. code-block:: java
+
+   String rutaRelativa = "/ruta/relativa/a/resources/archivo.txt"
+   InputStream st = getClass().getResourceAsStream(rutaRelativa);
+
+.. caution:: Se está suponiendo que el código está dentro de un método de
+   instancia y, por tanto, se dispone del objeto ``this``. Si el método es
+   estático, entonces debe utilizarse directamente la clase:
+
+   .. code-block:: java
+
+      // El método está, por ejemplo, en la clase 'Main'. 
+      InputStream st = Main.class.getResourceAsStream(rutaRelativa);
+
+.. 
+
 En consecuencia, a partir de este punto podemos tratar estas tres entradas
 diferentes de un mismo modo (p.e. usando la clase :java-util:`Scanner
 <Scanner>`). Si el archivo lo vamos a manejar por líneas lo más adecuado es

source/03.xml/01.jaxp.rst

@@ -14,12 +14,11 @@ Comencemos por conocer cómo abrir un documento |XML| y acceder a sus nodos:
 
 .. code-block:: java
 
-   Path ruta = Path.of(System.getProperty("user.home"), "claustro.xml");
    DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
    // La siguiente línea puede provocar un ParseConfigurationException
    DocumentBuilder builder = factory.newDocumentBuilder();
 
-   try (InputStream st = Files.newInputStream(ruta)) {
+   try (InputStream st = getClass().getResourceAsStream("/claustro.xml")) {
       // La línea posterior también puede generar una excepción.
       Document xml = builder.parse(st);
       // Accedemos a la información del documento a través de su DOM.
@@ -39,14 +38,11 @@ Comencemos por conocer cómo abrir un documento |XML| y acceder a sus nodos:
    <jaxp-dtd>`.
 
 Una vez tenemos disponible el objeto `Document` ya podremos acceder a los nodos
-del documento. En principio, los nodos se modelan mediante la clase `Node
-<https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html>`_ sobre la que
-construyen subsclases que modelan los distintos tipos de nodos (`Element
-<https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Element.html>`_, `Text
-<https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Text.html>`_, `Attr
-<https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Attr.html>`_, etc.). Cada
-uno de estos tipos de nodos está asociado a un número entero al que se da 
-nombre mediante un atributo estático de `Node`_. Por ejemplo:
+del documento. En principio, los nodos se modelan mediante la clase |Node| sobre
+la que construyen subsclases que modelan los distintos tipos de nodos
+(|Element|, |Text|, |Attr|, etc.). Cada uno de estos tipos de nodos está
+asociado a un número entero al que se da nombre mediante un atributo estático de
+|Node|. Por ejemplo:
 
 .. code-block:: java
 
@@ -73,7 +69,7 @@ hacer diversas pesquisas:
 
 ``getNodeValue()``
    devuelve el valor del nodo. Dependiendo del tipo de nodo, así será su valor
-   (al comienzo de la explicación sobre Node_ hay una tabla que indica qué valor
+   (al comienzo de la explicación sobre |Node| hay una tabla que indica qué valor
    devuelve cada tipo).
 
 ``getTextContent()``
@@ -89,8 +85,8 @@ hacer diversas pesquisas:
 
    .. code-block:: java
 
-      // apelativo es una variable que contiene el elemento apelativo comentado
-      apelativo.getTextContent() == apelativo.firstChild().getNodeValue();
+      // apelativo es una variable que contiene el elemento apelativo antedicho
+      apelativo.getTextContent().equals(apelativo.firstChild().getNodeValue());
 
 ``getFirstChild()`` o ``getLastChild()``
    Devuelve el primero o el último **nodo** hijo de aquel. Se ha remarcado nodo,
@@ -101,13 +97,11 @@ hacer diversas pesquisas:
    devuelve el nodo padre o el hermano previo o el hermano siguiente.
 
 ``getChildNodes()``
-   devuelve un objeto `NodeList
-   <https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/NodeList.html>`_  con
-   los nodos hijos. A pesar de su naturaleza no implementa la interfaz
-   :java-lang:`Iterable <Iterable>` y sólo presenta un método (``getLength()``)
-   que devuelve la cantidad de hijos y un método ``item(int index)`` que
-   devuelve el i-ésimo nodo de la lista. Por tanto, si se quiere quiere recorrer
-   la colección, habrá que usar un `for` clásico:
+   devuelve un objeto |NodeList| con los nodos hijos. A pesar de su naturaleza
+   no implementa la interfaz :java-lang:`Iterable <Iterable>` y sólo presenta un
+   método (``getLength()``) que devuelve la cantidad de hijos y un método
+   ``item(int index)`` que devuelve el i-ésimo nodo de la lista. Por tanto, si
+   se quiere quiere recorrer la colección, habrá que usar un `for` clásico:
 
    .. code-block:: java
 
@@ -124,7 +118,7 @@ hacer diversas pesquisas:
       }
 
   .. tip:: Pese a que, a priori, sólo podemos utilizar el `for` tradicional
-     para recorrer NodeList_, podemos buscarnos las vueltas para convertirlo
+     para recorrer |NodeList|, podemos buscarnos las vueltas para convertirlo
      en un flujo y poder usar con él técnicas de :ref:`Java funcional <funcional>`:
 
      .. code-block:: Java
@@ -133,12 +127,11 @@ hacer diversas pesquisas:
         Stream<Node> streamNode = IntStream.range(0, hijos.getLength()).mapToObj(hijos::item);
 
 ``getAttributes()``
-   devuelve los atributos del elemento en forma de `NamedNodeMap
-   <https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/NamedNodeMap.html>`_
-   que como NodeList_ tampoco implemente la interfaz :java-lang:`Iterable
-   <Iterable>`. Además de ``item(int index)`` y ``getLength()``, dispone también
-   de ``getNamedItem(String name)`` que permite obtener el nodo atributo a
-   partir de su nombre:
+   devuelve los atributos del elemento en forma de |NamedNodeMap| que como
+   |NodeList| tampoco implemente la interfaz :java-lang:`Iterable <Iterable>`.
+   Además de ``item(int index)`` y ``getLength()``, dispone también de
+   ``getNamedItem(String name)`` que permite obtener el nodo atributo a partir
+   de su nombre:
 
    .. code-block:: java
 
@@ -151,12 +144,12 @@ hacer diversas pesquisas:
       }
 
 Por otra parte, los tipos de nodos tiene también sus métodos específicos. Por
-ejemplo, Element_:
+ejemplo, |Element|:
 
 ``getElementsByTagName(String name)``
    devuelve los elementos descendientes cuyo nombre de etiqueta es el
    suministrado en el argumento. El método también existe para los nodo
-   `Document <https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Document.html>`_:
+   |Document|:
 
    .. code-block:: java
 
@@ -172,7 +165,7 @@ ejemplo, Element_:
       Element p17 = xml.getElementById("p17"); // null, porque no estamos usando el DTD
 
 ``getAttributeNode(String name)`` o ``getAttribute(String name)``
-   devuelve el atributo (Attr_) o el valor del atributo cuyo nombre se
+   devuelve el atributo (|Attr|) o el valor del atributo cuyo nombre se
    proporciona en el argumento.
 
 .. _jaxp-dtd:
@@ -303,7 +296,7 @@ crearlo *ex novo*:
 
 Escritura a archivo
 -------------------
-Partamos de que ya tenemos un Document_ construido como queremos que quede
+Partamos de que ya tenemos un |Document| construido como queremos que quede
 (véase el apartado anterior) y queremos ahora generar el |XML| correspondiente:
 
 .. code-block:: java
@@ -385,11 +378,19 @@ si nuestra intención es usarla una sola vez:
 
 .. [#] En realidad el método tiene sentido para otros nodos que no sean
    elementos. Véase la tabla que resume sus significados en la explicación del
-   método que ofrece la documentación original de Node_.
+   método que ofrece la documentación original de |Node|.
 
 .. |JAXP| replace:: :abbr:`JAXP (Java API for XML Processing)`
 .. |XML| replace:: :abbr:`XML (eXtensible Markup Language)`
 .. |DOM| replace:: :abbr:`DOM (Document Object Model)`
 .. |DTD| replace:: :abbr:`DTD (Document Type Definition)`
 .. |JDK| replace:: :abbr:`JDK (Java Development Kit)`
 .. |URL| replace:: :abbr:`URL (Uniform Resource Locator)`
+
+.. |Node| replace:: :java-jaxp:`Node`
+.. |Element| replace:: :java-jaxp:`Element`
+.. |Attr| replace:: :java-jaxp:`Attr`
+.. |Text| replace:: :java-jaxp:`Text`
+.. |NodeList| replace:: :java-jaxp:`NodeList`
+.. |NamedNodeMap| replace:: :java-jaxp:`NamedNodeMap`
+.. |Document| replace:: :java-jaxp:`Document`

source/98.apendices/15.cli.rst

@@ -434,9 +434,11 @@ a. Crear un archivo dentro de :file:`src/main/resources` que copie los valores
       app.version=${project.version}
       app.description=${project.description}
 
+   .. _add-resources:
 
-#. Añadir en :file:`pom.xml` un sección que habilite la sustitución de las
-   variables incluidas en el archivo anterior por sus valores:
+#. Añadir en :file:`pom.xml` un sección que añada el archivo al proyecto y
+   habilite la sustitución de las variables incluidas en el archivo anterior
+   por sus valores:
 
    .. code-block:: xml
 

source/conf.py

@@ -48,6 +48,7 @@
     'java-io': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/io/%s.html', 'java.io.%s'),
     'java-nio': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/nio/file/%s.html', 'java.nio.file.%s'),
     'java-lang': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/lang/%s.html', '%s'),
+    'java-jaxp': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.xml/org/w3c/dom/%s.html', '%s'),
     'java-function': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/function/%s.html', 'java.util.function.%s'),
     'java-stream': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/stream/%s.html', 'java.util.stream.%s'),
     'java-sql': ('https://docs.oracle.com/en/java/javase/23/docs/api/java.sql/java/sql/%s.html', 'java.sql.%s'),