UD2 · Sección 2 — Clases y objetos en la API de Java

Dato	Valor
Unidad Didáctica	UD2 — Programación Orientada a Objetos con la API de Java
Resultado de Aprendizaje	RA2 — Escribe y prueba programas sencillos, reconociendo y aplicando los fundamentos de la programación orientada a objetos.
Sección	2 de 10 — Clases y objetos en la API de Java
Evaluación	1.ª Evaluación
Duración estimada	2,5 horas lectivas
Criterios de evaluación cubiertos	CE 2.2 (escribe programas simples), CE 2.3 (instancia objetos a partir de clases predefinidas), CE 2.4 (utiliza métodos y propiedades), CE 2.5 (llamadas a métodos estáticos), CE 2.6 (utiliza parámetros), CE 2.7 (incorpora librerías de objetos)
Prerrequisitos	UD1 completa, UD2 Sección 1
Paquete del código de ejemplo	`dam.programacion.ud2`
Herramientas	JDK 25, IntelliJ IDEA Community, Maven 3.9.x, navegador web

1. Punto de partida

En la sección anterior sentaste las bases conceptuales de la POO: clase, objeto, new, pila vs. montículo, operador punto y los cuatro pilares. Pero lo ilustramos todo con String y System.out.println, porque era lo único que conocías.

Ahora toca abrir la caja de herramientas. Java viene de fábrica con miles de clases listas para usar: texto, números, fechas, listas, ficheros, redes, criptografía... No tienes que programar nada desde cero: el 80% del trabajo profesional en Java consiste en conocer y combinar bien las clases que ya existen. Esta sección te enseña a encontrarlas, a leerlas y a usarlas correctamente en IntelliJ. Es, literalmente, aprender a usar el catálogo antes de empezar a construir.

2. El API de Java: qué es y cómo se organiza

2.1. Qué es el API

El API (Application Programming Interface) de Java es el conjunto de clases, interfaces y métodos incluidos en el JDK que puedes usar sin instalar nada adicional. Lo mantiene Oracle, lo prueban cientos de ingenieros y está en producción en millones de programas. Aprovecharlo es usar el trabajo de gente que lleva décadas pensando en problemas que tú aún no te has encontrado.

Cuando en UD1 creaste tu primer proyecto Maven, el JDK 25 ya incluía todo este API. No necesitas añadir dependencias: con import basta.

2.2. Paquetes: la organización del API

Java organiza sus clases en paquetes, como carpetas en un sistema de archivos. Cada paquete agrupa clases relacionadas por temática. La convención de nombres es jerárquica con puntos.

Paquete	Contenido	Cuándo se usa
`java.lang`	Clases fundamentales: `String`, `System`, `Math`, `Integer`, `Object`	Siempre; se importa automáticamente
`java.util`	Utilidades: `Random`, `Scanner`, colecciones	Para entrada por teclado, aleatorios, listas
`java.time`	API moderna de fechas y horas: `LocalDate`, `LocalTime`	Para fechas (sustituye a `Date` y `Calendar`)
`java.math`	`BigInteger`, `BigDecimal`	Para números con precisión arbitraria (dinero, criptografía)
`java.io`	Entrada/salida clásica	Para leer/escribir ficheros (se verá en UD5)
`java.nio`	Entrada/salida moderna: `Path`, `Files`	Para ficheros (se verá en UD5)

En esta sección nos centraremos en los cuatro primeros; java.io y java.nio los verás en la UD5.

Analogía del supermercado. Imagina un supermercado grande con secciones: lácteos (java.lang), frutería (java.util), panadería (java.time), charcutería (java.math). Si quieres leche, vas a lácteos; si quieres manzanas, a frutería. En Java, si quieres un String, lo encuentras en java.lang; si quieres un Random, en java.util; si quieres un LocalDate, en java.time.

2.3. La regla de `java.lang`

Las clases del paquete java.lang son tan fundamentales que Java las importa automáticamente. No necesitas escribir import java.lang.String;: ya está disponible. Por eso en UD1 escribiste directamente String nombre = "Maria" sin ningún import.

En cambio, para usar Random (que está en java.util) sí necesitas importar:

import java.util.Random;

public class Ejemplo {
    public static void main(String[] args) {
        Random generador = new Random();
        int dado = generador.nextInt(6) + 1;  // del 1 al 6
        System.out.println("Has sacado un " + dado);
    }
}

Si quitas el import, IntelliJ lo marca en rojo y no compila. Es un error muy común al principio: olvídate de un import y el compilador dirá "cannot find symbol". IntelliJ te ayuda con Alt+Enter para añadir el import automáticamente.

2.4. Tabla de paquetes clave para UD2

Paquete	Clases que verás en esta unidad	Sección
`java.lang`	`String`, `Math`, `Integer`, `Double`, `Boolean`, `Character`, `Object`, `System`, `StringBuilder`	S1, S3, S7, S8
`java.util`	`Random`, `StringJoiner`	S5, S7
`java.time`	`LocalDate`, `LocalTime`, `LocalDateTime`, `Period`, `Duration`, `DateTimeFormatter`	S6
`java.math`	`BigDecimal` (mención breve)	S4 (complemento)

3. Cómo leer la documentación oficial (Javadoc)

3.1. Qué es Javadoc

Javadoc es el nombre de dos cosas a la vez: un formato de documentación (los comentarios /** ... */ que ya viste en UD1) y la herramienta que genera páginas HTML a partir de esos comentarios. Cuando hablamos de "la documentación de Java", casi siempre nos referimos al Javadoc HTML publicado oficialmente.

La URL oficial para Java 25 es: https://docs.oracle.com/en/java/javase/25/docs/api/

Esa página es tu mejor amiga durante el resto del curso. Aprender a leerla es una habilidad tan importante como aprender la sintaxis.

3.2. Anatomía de una página Javadoc

Vamos a desmenuzar la página de la clase String: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html

Use mouse to pan and zoom

flowchart TB
    A["Cabecera<br/>paquete y nombre de la clase"] --> B["Descripcion<br/>que es y para que sirve"]
    B --> C["Resumen de campos<br/>constantes y atributos publicos"]
    C --> D["Resumen de constructores<br/>formas de crear instancias"]
    D --> E["Resumen de metodos<br/>lista con firma breve"]
    E --> F["Detalle de metodos<br/>explicacion completa, parametros,<br/>retorno, excepciones"]

Las secciones más útiles para ti:

Descripción general: qué hace la clase y particularidades. Por ejemplo, en la de String se explica que es inmutable.
Constructor summary: las formas de crear objetos de esa clase.
Method summary: tabla con todos los métodos públicos, su firma y una frase descriptiva. Es lo que más usarás.
Method detail: explicación exhaustiva de cada método: parámetros, retorno, excepciones, ejemplos.

3.3. Cómo buscar un método

Imagina que necesitas poner un texto en mayúsculas. No recuerdas el método. Procedimiento:

Abre la página de String en el Javadoc.
Pulsa Ctrl+F en el navegador y escribe "uppercase".
Encuentras: String toUpperCase() — "Converts all of the characters in this String to upper case".
Haz clic en el nombre del método para ver el detalle, donde verás casos límite (¿qué pasa con la 'ñ'? ¿y con caracteres chinos?).

En diez segundos tienes la respuesta.

3.4. Convenciones que debes reconocer

Notación en Javadoc	Significado
`static`	Método estático: se llama con `Clase.metodo()`
(sin `static`)	Método de instancia: se llama con `objeto.metodo()`
`String` en mayúsculas	Tipo de retorno o parámetro: clase
`int`, `boolean`, `char`	Tipo primitivo
`String[]`	Array de strings
`throws IOException`	El método puede lanzar esa excepción (lo verás en UD3)
`@param`	Descripción de un parámetro
`@return`	Descripción del valor de retorno
`@since 1.0`	Versión de Java en la que se añadió
`@since 21`	Añadido en Java 21; no está en versiones anteriores

3.5. Javadoc dentro de IntelliJ

No necesitas abrir el navegador. IntelliJ incluye la documentación en el IDE:

Quick Documentation: cursor sobre cualquier clase o método y Ctrl+Q (Windows/Linux) o Ctrl+J (Mac). Aparece una ventana emergente con la documentación.
External Documentation: Shift+F1 abre la página HTML oficial en el navegador.
Go to Declaration: Ctrl+B o Ctrl+Click te lleva al código fuente del método (si el JDK tiene adjuntos los fuentes, configurado en UD1).

Estos tres atajos te ahorrarán horas a lo largo del curso.

4. Método de instancia vs. método estático: en profundidad

En la sección 1 introdujimos la distinción. Ahora la profundizamos, porque es la fuente número uno de confusiones para principiantes y porque la mayoría de los métodos del API caen claramente en una de las dos categorías.

4.1. Tabla comparativa

Aspecto	Método de instancia	Método estático
Pertenece a	Un objeto concreto	La clase entera
Cómo se llama	`objeto.metodo(args)`	`Clase.metodo(args)`
Necesita `new`	Sí, un objeto previo	No
Accede a atributos de instancia	Sí	No (no hay objeto)
Ejemplo en `String`	`length()`, `charAt(int)`, `toUpperCase()`	`String.format(...)`, `String.join(...)`, `String.valueOf(int)`
Ejemplo en `Math`	(no hay; todos sus métodos son estáticos)	`Math.max`, `Math.sqrt`, `Math.random`
Ejemplo en `Integer`	`intValue()`, `compareTo(Integer)`	`Integer.parseInt(String)`, `Integer.toBinaryString(int)`

4.2. Cómo distinguirlos leyendo el Javadoc

En el resumen de métodos, los estáticos aparecen marcados con la palabra static al inicio de la firma. Los de instancia no llevan esa palabra.

// Metodo estatico (en el Javadoc aparece "static" al inicio)
static String format(String format, Object... args)

// Metodo de instancia (no aparece "static")
int length()

4.3. Reglas mentales

Para decidir si un método es de instancia o estático, pregúntate:

"¿Tiene sentido este método sin un objeto concreto?" Si la respuesta es no, es de instancia. La longitud de un string depende de qué string concreto sea.
"¿Es una utilidad general que no depende de ningún estado concreto?" Si la respuesta es sí, es estático. Math.max(3, 7) no depende de ningún objeto; solo opera con los parámetros.

4.4. La trampa de `Integer`

La clase Integer tiene ambos tipos de métodos, lo que es una buena oportunidad para entender la distinción:

// Metodo estatico: no necesitas un Integer, solo quieres parsear
int edad = Integer.parseInt("23");        // String -> int

// Metodo de instancia: necesitas un Integer concreto
Integer numero = 42;
int valor = numero.intValue();             // Integer -> int
int comparacion = numero.compareTo(50);    // -1 porque 42 < 50

parseInt es estático porque su trabajo es crear un int a partir de un String; no necesita ningún Integer preexistente. intValue es de instancia porque te dice el valor entero de un objeto Integer concreto: sin objeto, no hay valor.

4.5. Por qué importa tanto

Mezclar ambos es uno de los errores de compilación más frecuentes al empezar:

// ERROR: length() es de instancia, pero intentas llamarlo como estatico
int n = String.length();  // no compila

// ERROR: parseInt es estatico, pero intentas llamarlo sobre un objeto
Integer i = 5;
int x = i.parseInt("23");  // compila pero hace otra cosa (heredado de Class)

La regla es: mira el Javadoc, mira si dice static y llama al método como corresponde. Si lo haces mal, IntelliJ te lo marcará en rojo.

5. IntelliJ: explorar la API con autocompletado

5.1. El autocompletado básico

Cuando escribes nombre. (siendo nombre una variable de tipo String) y pulsas Ctrl+Espacio, aparece una lista desplegable con todos los métodos disponibles. Es la forma más rápida de explorar una clase que no conoces.

String nombre = "Maria";
nombre.   // pulsa Ctrl+Espacio aqui
// Aparece: charAt, length, substring, toUpperCase, trim, ...

Cada entrada muestra la firma del método y, a la derecha, el tipo de retorno. Si seleccionas uno, IntelliJ te muestra los parámetros que espera.

5.2. Atajos imprescindibles para explorar el API

Atajo	Acción
`Ctrl+Espacio`	Autocompletado básico
`Ctrl+Shift+Espacio`	Autocompletado inteligente (filtra por tipo esperado)
`Ctrl+Q`	Ver documentación Javadoc del elemento bajo el cursor
`Ctrl+B`	Ir a la declaración (al código fuente del método o clase)
`Ctrl+Alt+B`	Ir a la implementación (útil con interfaces)
`Alt+Enter`	Solucionar problemas: añadir import, corregir errores
`Shift+F1`	Abrir documentación externa en el navegador
`Ctrl+F12`	Ver la estructura del archivo actual (métodos, campos)
`Ctrl+N`	Buscar una clase por nombre en todo el proyecto y librerías

5.3. Caso práctico: encontrar la clase correcta

Imagina que necesitas un número aleatorio. No recuerdas la clase. Procedimiento:

Pulsa Ctrl+N, escribe "Random". IntelliJ te muestra java.util.Random. Ya sabes dónde vive.
Pulsa Ctrl+B sobre Random para ver la clase (o Ctrl+Q para la documentación).
En la lista de métodos encuentras nextInt(int bound) — "Returns a pseudo-random int value between 0 (inclusive) and the specified bound (exclusive)".
Escribes:

import java.util.Random;

public class Dado {
    public static void main(String[] args) {
        Random generador = new Random();
        int tirada = generador.nextInt(6) + 1;  // 1 a 6
        System.out.println("Has sacado un " + tirada);
    }
}

Todo esto sin salir de IntelliJ y sin abrir el navegador.

6. Ejemplo integrador

Programa que combina varias clases del API y demuestra instancias vs. estáticos, lectura de Javadoc y uso de IntelliJ. No introduce contenido de secciones posteriores más allá de lo imprescindible para que el ejemplo sea significativo.

package dam.programacion.ud2;

import java.util.Random;

/**
 * Ejemplo integrador de la Seccion 2 de UD2.
 * Demuestra:
 * - Import de clases de java.util
 * - Instanciacion con new
 * - Metodos de instancia (Random.nextInt, String.length, String.toUpperCase)
 * - Metodos estaticos (Integer.parseInt, String.valueOf)
 * - Uso de la documentacion Javadoc
 */
public class ExplorandoAPI {

    public static void main(String[] args) {

        // 1. Importamos java.util.Random para crear un generador de aleatorios
        Random generador = new Random();

        // 2. Metodo de instancia: nextInt depende del objeto "generador"
        int dado = generador.nextInt(6) + 1;  // 1 a 6
        System.out.println("Has sacado un " + dado);

        // 3. Metodo estatico: parseInt pertenece a la clase Integer
        String edadTexto = "23";
        int edad = Integer.parseInt(edadTexto);
        System.out.println("Edad: " + edad);

        // 4. Concatenacion con + y metodo de instancia length()
        String nombre = "Maria";
        System.out.println("Hola, " + nombre + " (longitud " + nombre.length() + ")");

        // 5. Metodo estatico String.valueOf: convierte int a String
        String edadComoTexto = String.valueOf(edad);
        System.out.println("Edad como texto: " + edadComoTexto);

        // 6. Encadenamiento de metodos de instancia
        String mayus = nombre.toUpperCase().substring(0, 3);
        System.out.println("Tres primeras letras en mayusculas: " + mayus);

        // 7. Combinacion: generamos un codigo de cliente aleatorio
        int numeroCliente = generador.nextInt(1000, 9999);  // 4 digitos (Java 17+)
        String codigo = "CLI-" + nombre.substring(0, 3).toUpperCase() + "-" + numeroCliente;
        System.out.println("Codigo de cliente: " + codigo);
    }
}

Salida (los números varían por ser aleatorios):

Has sacado un 4
Edad: 23
Hola, Maria (longitud 5)
Edad como texto: 23
Tres primeras letras en mayusculas: MAR
Codigo de cliente: CLI-MAR-4827

Antes de ejecutarlo, intenta predecir qué métodos son estáticos y cuáles de instancia sin mirar el código. Si aciertas, has entendido la sección.

7. Errores comunes

Error	Qué pasa	Cómo evitarlo
Olvidar el `import`	"cannot find symbol" en compilación	`Alt+Enter` sobre la clase subrayada en rojo; IntelliJ añade el import
Llamar a un método estático como si fuera de instancia	Compila a veces (herencia) pero hace otra cosa	Mira el Javadoc; si dice `static`, usa `Clase.metodo()`
Llamar a un método de instancia como si fuera estático	No compila	Necesitas un objeto; primero `new`
Confundir `nextInt(int)` con `nextInt(int, int)`	El segundo solo existe desde Java 17+	Comprueba la versión en el Javadoc (`@since`)
No leer el Javadoc y adivinar la firma	Comportamiento inesperado	Usa `Ctrl+Q` antes de usar un método desconocido
Buscar en internet en vez de en el Javadoc	Información desactualizada	Empieza siempre por el Javadoc oficial

8. Resumen

Concepto	Idea clave
API de Java	Conjunto de clases incluidas en el JDK, listas para usar
Paquete	Agrupación de clases relacionadas; como una carpeta
`java.lang`	Paquete fundamental, se importa automáticamente
`java.util`, `java.time`, `java.math`	Otros paquetes clave; requieren `import`
Javadoc	Documentación oficial en HTML; URL de Java 25: docs.oracle.com
Método de instancia	Pertenece a un objeto; se llama `objeto.metodo()`
Método estático	Pertenece a la clase; se llama `Clase.metodo()`
IntelliJ autocompletado	`Ctrl+Espacio` para ver métodos disponibles
IntelliJ documentación	`Ctrl+Q` para ver Javadoc dentro del IDE
IntelliJ ir a declaración	`Ctrl+B` para ver el código fuente

9. Cuestionario de autoevaluación

Responde mentalmente o por escrito antes de mirar las soluciones. Si fallas, vuelve a la sección correspondiente.

Preguntas

¿Qué es el API de Java y qué relación tiene con el JDK?
Nombra tres paquetes del API de Java e indica para qué sirve cada uno.
¿Por qué no necesitas escribir import java.lang.String; al principio de tus archivos?
Si en el Javadoc de un método ves la palabra static al inicio de su firma, ¿cómo debes invocarlo? Pon un ejemplo.
¿Es length() un método de instancia o estático de la clase String? Justifica tu respuesta.
¿Es Integer.parseInt(String) un método de instancia o estático? ¿Por qué?
¿Qué atajo de IntelliJ te permite ver la documentación Javadoc de un método sin salir del IDE?
¿Qué atajo te lleva a la declaración (código fuente) de un método o clase?
Si escribes String.length() en tu código, ¿qué ocurre al compilar? ¿Por qué?
Tu programa necesita generar números aleatorios. ¿Qué clase usarías y en qué paquete está?
¿Cuál es la diferencia principal entre Integer y int? (Pista: uno es clase, el otro es primitivo.)
¿Qué representa la anotación @since 21 en el Javadoc de un método? ¿Por qué es importante?
Imagina que necesitas saber si un String empieza por "SR-". ¿Qué método usarías? ¿Es de instancia o estático?
¿Por qué se dice que Math es una clase "de utilidades"? ¿Tiene métodos de instancia?
Rellena los huecos: "Para usar la clase Scanner (que está en java.util) tengo que escribir _ al principio del archivo; para usar System.out.println() no necesito ningún _ porque System está en ____ que se importa automáticamente."

Soluciones

El API de Java es el conjunto de clases, interfaces y métodos incluidos en el JDK y disponibles sin instalar dependencias adicionales. El JDK incluye el API, el compilador y la JVM.
Posibles respuestas: java.lang (clases fundamentales como String, System, Math); java.util (utilidades como Random, Scanner, colecciones); java.time (fechas modernas como LocalDate); java.math (BigDecimal, BigInteger); java.io y java.nio (ficheros).
Porque el paquete java.lang se importa automáticamente en todos los archivos Java. Es una regla del lenguaje para las clases fundamentales.
Se invoca con el nombre de la clase, no con un objeto: Clase.metodo(args). Ejemplo: Integer.parseInt("23") o Math.max(3, 7).
Es de instancia, porque la longitud depende del string concreto sobre el que se invoque. No existe una "longitud universal" de String. Se llama nombre.length(), no String.length().
Es estático, porque parsear un texto a número es una operación que no depende de ningún objeto Integer concreto: recibe un String y devuelve un int. Se llama Integer.parseInt("23").
Ctrl+Q (Windows/Linux). En Mac se suele usar Ctrl+J o F1 según la configuración.
Ctrl+B (también funciona Ctrl+Click sobre el elemento).
No compila. length() es de instancia, así que necesita un objeto concreto: nombre.length(). Llamarlo como String.length() da error de sintaxis.
java.util.Random. También existe ThreadLocalRandom (en el mismo paquete) para uso concurrente; se verá en la sección 5.
int es un tipo primitivo de 32 bits; Integer es una clase (wrapper) que envuelve un int y permite tratarlo como objeto. Integer ofrece métodos estáticos como parseInt y constantes como MAX_VALUE.
Indica que el método se añadió en Java 21. Es importante porque si tu proyecto usa una versión anterior, ese método no existirá y el código no compilará. En este curso usamos Java 25, así que todo lo marcado @since hasta 25 está disponible.
startsWith(String), método de instancia. Se usa así: texto.startsWith("SR-").
Es de utilidades porque todos sus métodos son estáticos: no necesitas crear un objeto Math para usarlos. No tiene métodos de instancia. De hecho, ni siquiera puedes instanciarla (su constructor es privado, concepto que se verá en UD4).
"Para usar la clase Scanner (que está en java.util) tengo que escribir import java.util.Scanner; al principio del archivo; para usar System.out.println() no necesito ningún import porque System está en java.lang que se importa automáticamente."

Evaluación del cuestionario

Aciertos	Nivel
14-15	Dominas la sección. Adelante con la siguiente.
10-13	Bien, pero repasa los puntos fallados antes de avanzar.
6-9	Repasa la sección completa, especialmente la parte de instancia vs. estático.
Menos de 6	Vuelve a leer la sección con calma y prueba el ejemplo integrador paso a paso en IntelliJ.

10. Información ampliada y próximos pasos

Javadoc oficial de Java 25: https://docs.oracle.com/en/java/javase/25/docs/api/
Tutorial de Oracle sobre paquetes: https://docs.oracle.com/javase/tutorial/java/package/index.html
Documentación de IntelliJ sobre autocompletado: https://www.jetbrains.com/help/idea/auto-completing-code.html
Lista completa de paquetes del JDK 25: https://docs.oracle.com/en/java/javase/25/docs/api/java.base-summary.html

Próximos pasos:

Practica el explorador del IDE. Abre IntelliJ, crea una clase nueva y prueba los atajos Ctrl+N, Ctrl+Q, Ctrl+B con clases como String, Math, Random. Habitúa tu mano a esos atajos; los usarás miles de veces.
Lee el Javadoc de String completo. Es largo, pero vale la pena para tener una visión general de qué existe y qué no.
Avanza a la Sección 3 de UD2. La clase String en profundidad: inmutabilidad, string interning, métodos de búsqueda, transformación, extracción, comparación y formateo. Es la clase que más usarás en toda tu carrera y merece su propia sección.