Navegar a través de la documentación de las APIs Java
Deberíamos acudir siempre a la documentación de las APIs Java tanto en el proceso de aprendizaje como cuando ya estamos desarrollando aplicaciones Java
- en el proceso de aprendizaje es vital acudir a esta documentación siempre que nos encontremos en cualquier libro o tutorial de Java Clases y métodos desconocidos
- acudiendo a esta documentación conseguiremos una información concisa y vital realtiva a las Clases y métodos desconocidos
- una vez ya estamos desarrollando aplicaciones Java, es mucho más rápido y eficaz buscar primero en la documentación soluciones concretas en vez de divagar entre libros y tutoriales Java donde podemos encontrar muchos ejemplos y soluciones pero que en la mayoría de los casos los ejemplos y soluciones ofrecidas por los autores de dichas publicaciones no son las que nosotros estamos buscando
Si hemos instalado la documentación en nuestro ordenador según el Apéndice - Descarga e instalación de la documentación de la API Java SE, tenemos que escribir c: en la URL de nuestro navegador y busacar la pagina Web index.html que se encuentra en la carpeta file:///c:/docs/javase/API/docs/api. Seguidamente hacemos clic sobre index.html
y vemos como se nos abre una página Web con la documentación de la API J2SE
la documentación nos muestra todos los paquetes de la API J2SE
para ver por ejemplo el contenido del paquete java.awt hacemos clic sobre el vinculo java.awt
la estructura de los paquetes en la documentación siempre es la misma. Primero de todo nos muestra un resumen de las Interfaces que pertenecen al paquete en cuestión con el título Interface Summary
seguidamente nos muestra un resumen de las Clases que pertenecen al paquete bajo el título Class Summary
para conocer la Clase Button hacemos clic sobre el enlace Button
las Clases en la documentación siempre nos muestran sus SuperClases.
- en este caso la Clase java.awt.Button hereda de java.awt.Component y esta Clase a su vez hereda de java.lang.Object que es la Superclase de todas las Clases Java.
también nos indica las Interfaces que una Clase pude llegar a implementar.
- en este caso de las cuatro Interfaces que implementa la Clase Button vamos a mencionar la Interfaz Serializable.
- todo Objeto que implemente esta Interfaz puede ser serializado o congelado.
- esto es útil por ejemplo si nos interesa que un Objeto siga teniendo el mismo estado, es decir los mismos valores de sus variables de instancia cuando la aplicación después de ser parada se vuelve a ejecutar.
- para ello primero habremos serializado o congelado el Objeto en cuestión en el disco duro y cuando volvemos a arrancar la aplicación, ésta irá a buscar dicho Objeto en forma de fichero en el disco duro y lo deserializará o descongelará. Un ejemplo de este tipo de serialización lo podemos ver en el curso Java – J2SE Avanzado (Standard Edition).
- también es muy util cuando se quieren realizar invocaciones a métodos que se encuentran en Objetos remotos. Es decir Objetos que no estan en nuestro ordenador sino que se encuentran en otro ordenador. Los argumentos que se pasan a estos métodos se serializan y viajan a través de la red para tomar vida en el otro ordenador, y si este ordenador tiene que devolver algún Objeto también lo serializa y toma vida en el ordenador origen. Esta dinámica de trabajo la podemos ver en el curso Java – J2EE Avanzado (Enterprise Edition).
todas las Clases también nos mostrarán un resumen de sus variables de instancia, atributos o campos bajo el título Field Summary.
- en este caso nos encontramos con variables finales que pertenecen a las Clases Component e ImageObserver. Recordemos que podemos saber que una variable es final a simple vista porque ésta está escrita con letras mayúsculas.
Todas las Clases nos muestran desde cuando se utilizan bajo el título Since. En este caso la Clase Button existe desde la primera versión de Java, es decir la JDK 1.0
también nos encontraremos siempre con diferentes vínculos relacionados con la Clase que estamos leyendo bajo el titulo See Also:.
- en este caso concreto ya las conoceremos cuando tengamos que hacer clic a un botón y este genere un evento para que sea tratado.
más adelante también conoceremos las Clase Internas (Inner Classes o Nested Classes). Todas ellas se encuentran bajo el título Nested Classes.
- en este caso estas Clases Internas tanto pueden pertenecer a la Clase Button o a su Superclase Component.
todas las Clases también nos mostrarán el Contructor o Constructores sobrecargados que contengan bajo el título Constructor Summary.
- en este caso nos encontramos con un Constructor sin argumentos llamado Button().
- la Clase Button es un JavaBean porque entre otras cosas tiene un Constructor sin argumentos. Los JavaBeans pueden ser componentes visuales o Clases no visuales. En el caso de que sean componentes visuales estos estarán en la paleta de componentes y podrán ser arrastrados al contenedor que corresponda. Decimos que un JavaBean necesita tener un Constructor no sobrecargado para que el componente en cuestión se cree sin ningún tipo de inicialización de sus variables de instancia.
- Cuando nos referimos a JavaBeans, a las variables de instancia se las denomina propiedades.
- en este caso también nos encontramos con un Constructror sobrecargado Button(String label) para que muestre directamente una cadena de carateres en el propio botón cuando éste sea creado con este Constructor sobrecargado
también todas las Clases muestran un resumen de todos sus métodos bajo el título Method Summary.
- en nuestro caso vamos a hacer clic sobre el método getLabel() que como podemos ver en la columna de la izquierda retorna un Objeto de tipo String.
los métodos siempre nos muestran su signatura completa con una explicación de lo que realiza el método en cuestión. Si el método retorna algún valor éste se explica bajo el título Returns: y si contiene argumentos, éstos se esplican bajo el título Parameters:. Si hay algún otro método que tenga alguna relación con el método que estamos leyendo lo podemos saber bajo el título See Also:
- en nuestro caso podemos ver que el método getLabel() retorna un Objeto de tipo String y que el método setLabel(String Label) espera que le pasemos un argumento con el nombre de una etiqueta.
también las Clases muestran los métodos que heredan de posibles Supercalses bajo el título Methods inherited from...
- en nuestro caso vamos a volver a la Clase Button y vamos a localizar el método getSize() que se encuentra en la Clase java.awt.Component. Para ello vamos a hacer clic sobre el mencionado método.
- en nuestro caso podemos ver que el método getSize() retorna un Objeto de tipo Dimension y que apareció en la versión JDK 1.1.
- el hecho de que apareciera en esta versión y no en la 1.0 es debido a que Sun pensó en los diferentes fabricantes creadores de entornos de desarrollo como Borland, IBM o Microsoft entre otros.
- para que todos estos fabricantes de IDEs pudieran crear sus entonos de desarrollo para crear aplicaciones escritas en lenguaje Java, Sun hizo que todos los componentes gráficos fueran JavaBeans.
- para que una Clase se considere que es un JavaBean tiene que cumplir los siguientes requisitos:
- tiene que tener un Constructor sin argumentos
- las propiedades tienen que ser privadas y los métodos de acceso conocidos como getters y setters tienen que ser públicos
- si es un componente gráfico además tiene que implementar la Interfaz Serializable.
- de esta forma los IDEs sin excepción pueden tener sus inspectores con sus propiedades y cambiar el valor de las varibles de instancia visualmente a través de dichos inspectores.
cuando vemos que un método es Deprecated esto significa que dicho método ha quedado obsoleto.
- en nuestro caso el método size() apareció en la primera versión de Java, pero al convertir los componentes visuales a JavaBeans en la versión 1.1 del JDK la documentación nos está indicando que cuando escribamos nuevo código no utilicemos este método sino que por el contrario utilicemos el método getSize() que sigue las convenciones de los JavaBeans.
- en el caso de que tengamos código realizado con la primera versión de Java, seguirá siendo operativo con versiones posteriores, pero no se descarta la posibilidad de que en el futuro el mencionado método desaparezca en una nueva versión y el código antiguo ya no sea compatible con el nuevo código.
- por tanto si estamos escribiendo nuevo código y vemos que en la documentación hay un método que quisiéramos utilizar pero este método está Deprecated mejor siempre utilicemos la alternativa que nos ofrece la mencionada documentación.
ahora vamos a hacer clic sobre el vínculo de la Clase Dimension
la explicación nos indica que la Clase Dimension encapsula la anchura y la altura de un componente gráfico
- en este caso, podemos ver que la anchura y la altura se encapsulan en las propiedades height y width y que tiene un Constructor sin argumentos más dos otros Constructores sobrecargados
ahora volvemos a la Clase Button y buscamos el método setSize(...) combinando las teclas Ctrl + f
hacemos clic sobre setSize y nos aparece la siguiente página Web correspondiente a la Clase Component
- en este caso podemos ver que este método está sobrecargado, porque tanto se le puede pasar como argumento un Objeto de tipo Dimension como dos enteros
ahora hacemos clic sobre el vínculo setSize(int, int) para ver la explicación referente a este método
ahora subimos hasta arriba de la página
y hacemos clic sobre el vínculo Package para volver a ver toda la lista de Clases pertenecientes al paquete java.awt
y hacemos clic sobre el vínculo correspondiente a la clase Frame.
nos aparece la jerarquía de la Clase Frame que hereda de java.awt.Window, que esta a su vez hereda de java.awt.Container, que esta a su vez hereda dejava.awt.Component y ésta finalmente hereda de java.lang.Object
si bajamos hacia el resumen de los métodos
podemos ver los métodos setResizable(boolean resizable) y setTitle(String title) entre otros
y finalmente hacemos clic sobre el vínculo de este último método para verlo en detalle
Infosintesis Solutions Group, S.L.
Formación, asesoramiento y desarrollo de proyectos informáticos
