Un entorno mal configurado es la causa número uno de abandono entre quienes empiezan a programar en Java. Los mensajes de error son crípticos ('javac' no se reconoce como un comando, JAVA_HOME is not set, UnsupportedClassVersionError) y no tienen nada que ver con programar. Esta lección elimina ese obstáculo de una vez: instalarás un JDK, comprobarás que funciona, entenderás por qué existen JAVA_HOME y PATH en lugar de limitarte a copiar comandos, compilarás y ejecutarás tu primer programa desde la terminal y elegirás el IDE con el que trabajarás durante todo el curso. Al terminar tendrás el proyecto bibliotech creado y listo para escribir código.

1. Qué JDK elegir y de dónde descargarlo
2. Instalación en Windows, macOS y Linux
3. Verificar la instalación: java -version y javac -version
4. JAVA_HOME y PATH: qué son y cómo configurarlos
5. Tu primer programa desde la terminal: HolaBiblioTech.java
6. JShell: el laboratorio para aprender
7. Elegir un IDE y crear el proyecto bibliotech
8. Estructura de carpetas recomendada
9. Errores Comunes y Consejos
10. Ejercicios

En la lección anterior quedó claro que necesitas un JDK (no un JRE), porque el JDK incluye el compilador javac. Lo que quizá no esperabas es que haya varios JDK distintos para la misma versión de Java.

Todos parten del mismo código fuente, OpenJDK, que es la implementación de referencia y de código abierto. Lo que cambia entre distribuciones es quién la compila, quién la firma, durante cuánto tiempo publica parches y bajo qué licencia.

Recomendación práctica: descarga Eclipse Temurin 21 (o 17 si prefieres ceñirte estrictamente a la versión mínima del curso) desde adoptium.net. Es gratuito sin matices, ampliamente usado en producción y no requiere cuenta de usuario para descargar.

Sobre la versión: este curso usa Java 17 como referencia y marca explícitamente lo que necesita una versión superior. Si instalas Java 21, todo funcionará igual y además tendrás disponibles las mejoras más recientes. Ambas son LTS.

Un detalle al descargar: elige el paquete correcto para tu procesador. En Windows y en la mayoría de PC con Linux será x64. En un Mac moderno (M1, M2, M3, M4) será aarch64/ARM64; en un Mac antiguo, x64. Descargar el binario equivocado provoca errores de arranque desconcertantes.

1. En adoptium.net, descarga el instalador .msi de Temurin para Windows x64, versión 21 (LTS), JDK (no JRE).
2. Ejecuta el instalador. En la pantalla de opciones personalizadas, activa estas dos casillas, que te ahorrarán todo el apartado 4:
   • Add to PATH
   • Set JAVA_HOME variable
3. Termina la instalación. El JDK quedará normalmente en C:\Program Files\Eclipse Adoptium\jdk-21.x.x-hotspot.
4. Abre una terminal nueva (PowerShell o Símbolo del sistema). Este paso es obligatorio: las terminales ya abiertas no ven las variables de entorno nuevas.

La forma más cómoda es Homebrew. Si no lo tienes, instálalo desde brew.sh. Después:

Si prefieres no usar Homebrew, descarga el instalador .pkg de Adoptium y ejecútalo; el JDK se instalará en /Library/Java/JavaVirtualMachines/.

macOS trae una utilidad muy útil, /usr/libexec/java_home, que localiza el JDK instalado. La usarás en el apartado 4.

En distribuciones basadas en Debian o Ubuntu, el paquete de los repositorios oficiales suele bastar:

En Fedora o RHEL:

Fíjate en los sufijos: en Debian/Ubuntu el paquete -jdk incluye el compilador, y en Fedora es el sufijo -devel. Si instalas openjdk-21-jre o java-21-openjdk a secas, tendrás JVM pero no javac.

Si tu distribución no ofrece la versión que quieres, descarga el .tar.gz de Adoptium y descomprímelo en /opt:

Nota para quien gestiona varias versiones: herramientas como SDKMAN! (sdkman.io) permiten instalar y cambiar entre JDKs con un comando (sdk install java 21-tem, sdk use java 17-tem). Es lo que usa mucha gente que trabaja con proyectos de distintas edades. No es necesario para el curso, pero merece la pena conocerlo.

Este es el momento de la verdad. Abre una terminal nueva y ejecuta los dos comandos:

Una salida correcta se parece a esto (los números concretos variarán):

Interpretemos qué te está diciendo cada comando:

• java -version muestra la versión de la JVM que se ejecutará. Si este comando responde, puedes ejecutar programas Java.
• javac -version muestra la versión del compilador. Si este comando falla pero el anterior funciona, tienes un JRE o una instalación incompleta: no podrás compilar.

Es fundamental que ambos números coincidan. Es muy común, en máquinas donde se han instalado varios JDK a lo largo del tiempo, encontrarse con un java de la versión 8 y un javac de la 21. En ese escenario compilas código moderno que tu JVM se niega a ejecutar, y aparece el temido UnsupportedClassVersionError.

Si alguno de los comandos responde con "no se reconoce como un comando interno o externo" (Windows) o "command not found" (macOS/Linux), el JDK está instalado pero el sistema no sabe dónde encontrarlo. Eso es exactamente lo que resuelve el siguiente apartado.

Son dos variables de entorno: valores de texto que el sistema operativo pone a disposición de todos los programas que arranca.

• PATH es una lista de directorios separados por ; (Windows) o : (macOS/Linux). Cuando escribes javac en la terminal, el sistema recorre esa lista en orden buscando un ejecutable con ese nombre y ejecuta el primero que encuentra. Si el directorio bin de tu JDK no está en el PATH, la terminal no encuentra javac aunque esté perfectamente instalado. Y si hay dos JDK en el PATH, gana el que aparece primero: esa es la causa habitual de versiones descuadradas.

• JAVA_HOME apunta a la carpeta raíz del JDK (la que contiene bin, lib, conf…), no a un ejecutable. No la usa la terminal, sino otras herramientas: Maven, Gradle, servidores de aplicaciones, scripts de arranque y algunos IDEs la leen para saber con qué JDK deben trabajar. Puedes tener Java funcionando en la terminal sin JAVA_HOME, pero en cuanto uses una herramienta del ecosistema te la pedirá.

1. Pulsa la tecla Windows y busca "Editar las variables de entorno del sistema".
2. Pulsa Variables de entorno….
3. En Variables del sistema, pulsa Nueva:
   • Nombre: JAVA_HOME
   • Valor: la ruta raíz del JDK, por ejemplo C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot
4. Selecciona la variable Path, pulsa Editar y añade una entrada nueva: %JAVA_HOME%\bin. Usar %JAVA_HOME% en lugar de la ruta completa es una buena práctica: el día que actualices el JDK, solo tendrás que cambiar JAVA_HOME.
5. Si hay entradas antiguas de otros Java (por ejemplo C:\ProgramData\Oracle\Java\javapath), muévelas por debajo de la tuya o elimínalas.
6. Acepta todo y abre una terminal nueva.

Para comprobarlo:

En PowerShell serían $env:JAVA_HOME y Get-Command java.

La configuración se hace en el fichero de arranque de tu shell: ~/.zshrc si usas zsh (el predeterminado en macOS moderno) o ~/.bashrc / ~/.bash_profile si usas bash. Añade al final:

En macOS:

En Linux (ajusta la ruta a la real de tu instalación):

Fíjate en el detalle de PATH="$JAVA_HOME/bin:$PATH": colocamos nuestro bin delante del PATH existente, para que gane frente a cualquier otro Java instalado. Después, recarga la configuración:

En Linux, si tienes varias versiones instaladas por el gestor de paquetes, el comando sudo update-alternatives --config java te permite elegir cuál es la predeterminada del sistema.

Vas a compilar y ejecutar un programa sin IDE. Aunque después trabajes siempre con IntelliJ o Eclipse, hacerlo una vez a mano es lo que convierte "compilar" en algo concreto en lugar de un botón mágico.

Crea una carpeta de trabajo y, dentro, un fichero llamado exactamente HolaBiblioTech.java:

Todavía no vamos a diseccionar esta estructura (eso es la lección 01-03), pero hay una regla que necesitas ya: el nombre del fichero debe coincidir con el nombre de la clase pública, incluidas las mayúsculas. La clase se llama HolaBiblioTech, así que el fichero es HolaBiblioTech.java. Si lo guardas como holabibliotech.java o Hola.java, el compilador lo rechazará con un mensaje del tipo "class HolaBiblioTech is public, should be declared in a file named HolaBiblioTech.java".

Salida esperada:

Los dos comandos merecen una explicación detallada:

• javac HolaBiblioTech.java recibe el nombre del fichero con extensión. Traduce el fuente a bytecode y crea HolaBiblioTech.class en el mismo directorio. Si no hay errores, no imprime nada: en las herramientas de línea de comandos, el silencio es señal de éxito.
• java HolaBiblioTech recibe el nombre de la clase, sin extensión y sin .class. Aquí es donde casi todo el mundo se equivoca la primera vez escribiendo java HolaBiblioTech.class, lo que produce un error de "clase no encontrada". La razón es conceptual: java no abre un fichero, sino que carga una clase por su nombre buscándola en el classpath (por defecto, el directorio actual).

Desde Java 11 existe un atajo muy cómodo para programas de un solo fichero:

Fíjate en que aquí sí lleva la extensión .java. Este modo compila el fichero en memoria y lo ejecuta al vuelo, sin dejar ningún .class en el disco. Es perfecto para pruebas rápidas y para aprender, pero tiene límites: solo sirve para programas contenidos en un único fichero fuente. En cuanto tu proyecto tenga varias clases (a partir del módulo 3), volverás a javac o, más probablemente, dejarás que el IDE lo haga por ti.

Java 9 introdujo JShell, una consola interactiva (lo que en otros lenguajes se llama REPL: read-eval-print loop). Te permite escribir expresiones sueltas y ver el resultado al instante, sin crear un fichero, sin clase y sin main.

Una sesión típica:

Observa un par de detalles:

• No hacen falta los puntos y coma al final de cada línea (aunque puedes ponerlos).
• Cuando una expresión no se guarda en una variable, JShell le asigna un nombre automático ($5, $6) que puedes reutilizar después.

Los comandos de JShell empiezan por barra:

Para qué te servirá durante el curso: cada vez que dudes de cómo se comporta algo ("¿qué devuelve exactamente 5/2?", "¿trim() elimina también los tabuladores?"), abrir JShell y probarlo en cinco segundos es infinitamente mejor que suponerlo. Úsalo sin reparos en los módulos 1, 4 y 5.

Un IDE (Integrated Development Environment) es un editor que además compila, ejecuta, depura, autocompleta y detecta errores mientras escribes. En Java es prácticamente imprescindible: el ecosistema profesional lo asume.

Para este curso la recomendación es IntelliJ IDEA Community Edition: su detección de errores en tiempo real y sus sugerencias son, en la práctica, un profesor invisible que te corrige mientras escribes. Dicho esto, cualquiera de los cuatro sirve; el código del curso es idéntico en todos.

1. Abre IntelliJ y pulsa New Project.
2. Rellena:
   • Name: bibliotech
   • Location: la carpeta donde guardas tus proyectos
   • Language: Java
   • Build system: IntelliJ (no elijas Maven ni Gradle todavía; los veremos en el módulo 11)
   • JDK: selecciona el 21 (o 17) que instalaste. Si no aparece, usa Add JDK… y navega hasta la carpeta de JAVA_HOME.
   • Desmarca Add sample code para partir de cero.
3. Pulsa Create.
4. En el panel izquierdo, pulsa el botón derecho sobre la carpeta src → New → Java Class y escribe HolaBiblioTech.
5. Pega el código del apartado 5 y pulsa el triángulo verde del margen para ejecutarlo. Verás la salida en la ventana Run.

File → New → Java Project, nombre bibliotech, selecciona el JRE/JDK 21 y desmarca la creación de module-info.java. Después, botón derecho sobre src → New → Class, nombre HolaBiblioTech, y marca la casilla que genera el método main.

Instala el Extension Pack for Java de Microsoft. Después, Ctrl+Shift+P → Java: Create Java Project → No build tools → elige carpeta y nombre bibliotech.

Aunque en este módulo trabajes con uno o dos ficheros, conviene adoptar desde ya la estructura estándar del mundo Java. Es la que espera Maven (módulo 11), la que reconocen todos los IDE y la que verás en cualquier proyecto profesional:

Tres ideas importantes de esta estructura:

• El código fuente y el compilado viven en carpetas separadas. Nunca mezcles .java y .class en el mismo sitio en un proyecto real: la carpeta de salida se borra y se regenera constantemente, y no se guarda en el control de versiones.
• Los directorios com/nexussoftware/bibliotech reflejan el paquete com.nexussoftware.bibliotech. En Java, la jerarquía de paquetes debe corresponderse con la de carpetas. Lo explicaremos en detalle en la lección siguiente; por ahora quédate con que no es decorativo.
• src/main y src/test separados anticipan la llegada de las pruebas automatizadas.

Sobre las herramientas de construcción: Maven y Gradle automatizan la compilación, la gestión de dependencias y el empaquetado. Son imprescindibles en cualquier proyecto real y les dedicaremos la lección 11-05 completa. En este módulo no los necesitas: añadirlos ahora solo introduciría ruido entre tú y el lenguaje.

• 'javac' no se reconoce como un comando. El directorio bin del JDK no está en el PATH, o has instalado un JRE. Revisa el apartado 4 y recuerda abrir una terminal nueva después de tocar variables de entorno.
• java -version y javac -version muestran versiones distintas. Tienes más de un Java instalado y el PATH los mezcla. Ejecuta where java / where javac (Windows) o which -a java javac (Unix) para ver todas las rutas activas y coloca la del JDK que quieras al principio del PATH.
• Error: Could not find or load main class HolaBiblioTech.class. Has escrito java HolaBiblioTech.class. El comando java recibe el nombre de la clase, sin extensión.
• class X is public, should be declared in a file named X.java. El nombre del fichero no coincide con el de la clase pública. Java distingue mayúsculas y minúsculas también aquí.
• UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime. Compilaste con un JDK más nuevo que la JVM con la que ejecutas. Unifica versiones, o compila con javac --release 17.
• No ver la extensión real de los ficheros en Windows. El explorador oculta las extensiones conocidas por defecto, y acabas con HolaBiblioTech.java.txt. Activa Ver → Extensiones de nombre de archivo antes de seguir.
• Consejo: guarda tus proyectos en una ruta sin espacios ni acentos (C:\dev\bibliotech, no C:\Mis Documentos\Programación\). Muchas herramientas del ecosistema Java siguen teniendo problemas con esas rutas.
• Consejo: dedica quince minutos a aprender tres atajos de tu IDE: ejecutar el programa, buscar una clase por nombre y renombrar un identificador en todo el proyecto. Es la mejor inversión de tiempo del curso.

Realiza una comprobación completa de tu instalación y anota los resultados:

1. Versión que reportan java -version y javac -version. ¿Coinciden?
2. Valor de JAVA_HOME.
3. Ruta física del ejecutable java que se está usando.
4. ¿Hay más de un Java instalado en tu máquina?

Escribe los comandos exactos que usarías en tu sistema operativo y explica qué te dice cada resultado.

Sin usar el IDE, crea en una carpeta llamada pruebas un fichero FichaLibro.java que imprima por consola la ficha del libro "Java Efectivo" con este formato exacto:

Compílalo y ejecútalo con javac y java. Después, ejecútalo con el modo de fichero único de Java 11+. Responde: ¿qué diferencia observas en el contenido de la carpeta tras cada método?

Abre JShell y, sin escribir ningún fichero, calcula la multa de un préstamo de BiblioTech: define una variable diasRetraso con valor 9, una constante tarifaDiaria con valor 0.25 y calcula la multa. Después usa /vars para listar lo definido. Finalmente, prueba a escribir titulo.length() sobre una variable titulo que no hayas definido y observa el mensaje de error.

Solución 1

En Windows (PowerShell):

En macOS / Linux:

Interpretación de los resultados:

• Si java -version y javac -version dan el mismo número mayor (por ejemplo, ambos 21), tu entorno es coherente y puedes compilar y ejecutar sin sorpresas.
• JAVA_HOME debe apuntar a la carpeta raíz del JDK. Si apunta a .../bin o está vacío, herramientas como Maven fallarán más adelante.
• which -a java (o where.exe java) es la clave del ejercicio: si devuelve más de una línea, tienes varios Java instalados y el que manda es el de la primera línea. Ahí se origina la mayoría de incoherencias de versión.

Solución 2

El fichero FichaLibro.java:

Compilación y ejecución clásicas:

Ejecución directa del fuente:

Diferencia observable: tras javac, la carpeta contiene dos ficheros: FichaLibro.java y FichaLibro.class. Tras la ejecución directa del fuente, sigue habiendo solo FichaLibro.java: la compilación se hace en memoria y el bytecode se descarta al terminar el programa. Por eso el modo directo es cómodo para probar, pero inservible para distribuir: no produce nada que puedas entregar.

Solución 3

Dos observaciones que conviene interiorizar ya:

• El resultado 2.25 sale de multiplicar un int por un double: Java convierte automáticamente el entero a decimal antes de operar. Es una conversión ensanchante, y la estudiarás formalmente en la lección 01-04.
• El error cannot find symbol es uno de los mensajes más frecuentes del compilador Java y significa siempre lo mismo: estás usando un nombre que el compilador no conoce. Las causas típicas son no haber declarado la variable, haberla escrito con otras mayúsculas o haberla declarado en un ámbito distinto. Aprender a reconocerlo de inmediato te ahorrará mucho tiempo.

Ya tienes un entorno funcional: un JDK LTS instalado, java y javac respondiendo con la misma versión, JAVA_HOME y PATH configurados y entendidos, tu primer programa HolaBiblioTech compilado y ejecutado desde la terminal, JShell disponible para experimentar y el proyecto bibliotech creado en tu IDE con la estructura de carpetas estándar. Todo lo que venga a partir de ahora es programar.

En la siguiente lección, Sintaxis y Estructura Básica, diseccionaremos ese fichero HolaBiblioTech.java palabra por palabra: qué significa exactamente public static void main(String[] args), qué son las sentencias y los bloques, cómo se comenta el código, qué convenciones de nomenclatura sigue todo el mundo en Java y por qué, cómo funcionan los paquetes y su relación con los directorios, y cómo leer los mensajes de error del compilador para no quedarte bloqueado nunca.