MANUAL DE USUARIO Librería SFTP Versión 1.0 Área de Aplicaciones Especiales y Arquitectura de Software Framework Atlas Librería SFTP Hoja de Control Título Manual de Usuario Uso de librería Jsch con el Framework Atlas. Documento de Referencia NORMATIVA ATLAS Responsable Área de Aplicaciones Especiales y Arquitectura de Software Versión 1.0 Fecha Versión 13/05/2014 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio Área de Integración y Arquitectura de 1.0 Versión inicial del documento Aplicaciones 2 de 20 13/05/2014 Framework Atlas Librería SFTP Índice 1. INTRODUCCIÓN ................................................................................................................................................................ 4 1.1. 1.2. AUDIENCIA OBJETIVO ...................................................................................................................................................... 4 CONOCIMIENTOS PREVIOS ............................................................................................................................................... 4 2. DESCRIPCIÓN .................................................................................................................................................................... 5 3. INSTALACIÓN Y CONFIGURACIÓN............................................................................................................................. 6 3.1. INSTALACIÓN .............................................................................................................................................................. 6 3.2. CONFIGURACIÓN ....................................................................................................................................................... 6 3.2.1. Paso 1: Parámetros de configuración del environment.properties ........................................................................ 6 4. USO ........................................................................................................................................................................................ 7 4.1. CREAR SERVICIO DE SFTP ............................................................................................................................................... 9 4.1.1. Crear interfaz del servicio de SFTP........................................................................................................................ 9 4.1.2. Crear implementación del servicio de SFTP ........................................................................................................ 11 4.1.3. Definir servicio de sftp en applicationContext-services.xml ................................................................................. 12 4.2. CREAR FACHADA ........................................................................................................................................................... 13 4.2.1. Crear interfaz de la fachada ................................................................................................................................. 13 4.2.2. Crear implementación de la fachada .................................................................................................................... 14 4.2.3. Definir fachada en applicationContext-services.xml ............................................................................................ 15 4.3. CREAR PRESENTACIÓN JSF ............................................................................................................................................ 15 4.3.1. Crear backing bean............................................................................................................................................... 15 4.3.2. Crear página JSF .................................................................................................................................................. 17 5. ENLACES RELACIONADOS .......................................................................................................................................... 18 6. ANEXOS .............................................................................................................................................................................. 19 6.1. INSTALACIÓN Y CONFIGURACIÓN DE SERVIDOR SSH FTP ............................................................................................. 19 6.1.1. Crear usuario del Servidor SSH FTP ................................................................................................................... 19 6.1.2. Establecer directorio del Servidor SSH FTP ........................................................................................................ 20 6.1.3. Establecer puerto del Servidor SSH FTP .............................................................................................................. 20 6.1.4. Iniciar servicio SSH del Servidor. ......................................................................................................................... 20 3 de 20 Framework Atlas Librería SFTP Contenido 1. INTRODUCCIÓN En este documento se explica cómo conectarse a un servidor SSH FTP, también conocido como SFTP y hacer una serie de operaciones como listar los ficheros que se encuentran en un directorio, subir, descargar y eliminar un fichero que se encuentra en el SFTP a través de una aplicación web. 1.1. Audiencia objetivo El lector objetivo de este documento es toda aquella persona que esté desarrollando una aplicación basada en el framework Atlas y necesite acceder y gestionar ficheros de un servidor de ficheros SSH FTP. 1.2. Conocimientos Previos Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: - Java Server Faces (JSF) - Spring Framework Para saber más sobre dichas tecnologías, consultar el apartado de este documento, Enlaces Relacionados 4 de 20 Framework Atlas Librería SFTP 2. DESCRIPCIÓN Para poder conectarse a un servidor SSH FTP usaremos la librería jsch la cual nos permite transferir seguramente ficheros sobre SSH, esta librería nos permite hacer una seria de operaciones sobre sftp como: Listar ficheros Subir ficheros Renombrar ficheros Descargar ficheros Crear directorios Eliminar directorios El resto de características se encuentran en la web de la librería http://www.jcraft.com/jsch/ El paquete principal que utilizaremos será com.jcraft.jsch.JSch el cual nos permitirá crear una sesión remota (session) en un servidor estableciendo el host, puerto y un usuario, una vez establecida la sesión indicaremos la clave, si toda va bien entonces tendremos una conexión abierta y podemos crear un canal (channel) El canal de uso aquí será de tipo “sftp” (pueden ser de tipo como Shell, exec y subsystem; más información en http://wiki.jsch.org/index.php?Manual#ae1f7edf), una vez abierto el canal sftp podemos hacer las operaciones comunes como rm, rmdir, mkdir, cd, get, put, etc. 5 de 20 Framework Atlas Librería SFTP 3. INSTALACIÓN Y CONFIGURACIÓN 3.1. INSTALACIÓN Para poder usar la librería java Jsch se deberá incluir la siguiente dependencia en el archivo pom.xml del proyecto. pom.xml <!-- 3.2. Dependencias para SFTP--> <dependency> <groupId>com.jcraft</groupId> <artifactId>jsch</artifactId> <version>0.1.51</version> </dependency> CONFIGURACIÓN Éste es el punto más importante, aquí definimos y configuramos los beans que usaremos para operar con los ficheros del servidor SSH SFTP. Para que los valores de los parámetros de configuración sean invisibles al entorno de la aplicación, estos son obtenidos del fichero environment.properties. 3.2.1. Paso 1: Parámetros de configuración del environment.properties Para establecer la configuración de conexión el SFTP se deberá ingresar los datos del servidor como el host (puede ser la ip del servidor), el puerto, el usuario, el directorio donde se descargan los ficheros, el directorio remoto donde se encuentras los ficheros que vamos a operar. La clave o password de acceso al servidor se deberá ingresar encriptada, para ello usar el servicio proporcionado por ICM en la página http://intranet.madrid.org/arquitecturasw/desarrollos-atlas/utilidades/encriptacion , el valor devuelto por ese servicio deberá ser el que se ingrese a la derecha de sftp.clave= environment.properties # Configuración de acceso a SFTP sftp.host=localhost sftp.puerto=22 sftp.usuario=usuario sftp.clave=7583256AF7A2BE12 sftp.dirDescarga=/borrame/ sftp.dirRemoto=. NOTA Para más información sobre el fichero de configuración environment.properties consultar el manual de arquetipos. 6 de 20 Framework Atlas Librería SFTP 4. USO Una vez configurado el entorno para el uso del servicio, puede procederse a su utilización. Análogamente al resto de servicios de Spring, para hacer uso de los beans de sftp, declararemos los atributos respectivos a cada uno de ellos en el servicio que los queramos usar -con sus métodos set correspondientes-. Ejemplo de listar ficheros 7 de 20 Framework Atlas Librería SFTP ..... /** * The sftpFacade, la fachada */ @ManagedProperty(value = "#{sftpFacade}") private SftpFacade sftpFacade; /** * @return the sftpFacade */ public SftpFacade getSftpFacade() { return sftpFacade; } /** * @param sftpFacade the sftpFacade to set */ public void setSftpFacade(SftpFacade sftpFacade) { this.sftpFacade = sftpFacade; } /** * Método que sirve para listar los fichero del directorio * remoto del SFTP. */ @SuppressWarnings("unchecked") public void listarFicheros() { try { Vector vFicheros = sftpFacade.listarFicheros(); agregarFicheros(vFicheros); } catch (ServiceException e) { AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "sftp.listar.error"); } } /** * Método que sirve para agregar ficheros * al componente select. * @param vFicheros Lista de ficheros. */ @SuppressWarnings("unchecked") private void agregarFicheros(Vector vFicheros) { ficheros = new ArrayList<SelectItem>(); int numeroFicheros = vFicheros.size(); for (int ii = 0; ii < numeroFicheros; ii++) { Object obj = vFicheros.elementAt(ii); if (obj instanceof LsEntry) { String nombreFichero = ((LsEntry) obj).getFilename(); agregarSelectItem(nombreFichero); } } } ..... 8 de 20 Framework Atlas Librería SFTP 4.1. Crear servicio de SFTP 4.1.1. Crear interfaz del servicio de SFTP Comenzamos con la implementación de un servicio, creando una interfaz, para obligarnos a implementar una serie de métodos, los típicos para sftp (listar, subir, descargar y eliminar ficheros). NOTA El servicio que se muestra a continuación no tiene como finalidad ser utilizado como servicio gestión de ficheros de un SFTP, simplemente se trata de un ejemplo de integración con el framework. Cada proveedor debe hacer los cambios oportunos para adecuarlos a sus necesidades. 9 de 20 Framework Atlas Librería SFTP Para nuestro ejemplo usaremos los siguientes: SftpService.java /** * Esta interfaz representa las operaciones * de operaciones con un servidor seguro SFTP. * @author ICM * @version 1.0. */ public interface SftpService { /** * Método que devuelve el listado ficheros del directorio remoto * del servidor SFTP. * @return Vector, listado de ficheros del directorio * @throws ServiceException ex */ @SuppressWarnings("unchecked") Vector listarFicheros() throws ServiceException; /** * Método que permite descargar un fichero del SFTP * @param fichero el fichero a descargar * @throws ServiceException ex */ void descargarFichero(String fichero) throws ServiceException; /** * Método que permite eliminar u fichero del SFTP * @param fichero el fichero a eliminar * @throws ServiceException ex */ void eliminarFichero(String fichero) throws ServiceException; /** * Método que permite subir un fichero al SFTP * @param nombreFichero el nombre del fichero * @param is inputstream del fichero * @throws ServiceException ex */ void subirFichero(InputStream is, String nombreFichero) throws ServiceException; } 10 de 20 Framework Atlas Librería SFTP 4.1.2. Crear implementación del servicio de SFTP Creamos la implementación de los métodos definidos en la interfaz SftpService. SftpServiceImpl.java /** * Esta clase representa el servicio de ejemplo de sftp */ @Service public class SftpServiceImpl implements SftpService { /** El host sftp */ private String host; /** El puerto del SFTP */ private int puerto; /** Usuario del sftp */ private String usuario; /** password para acceder al sftp */ private String password; /** directorio remoto del sftp*/ private String dirRemoto; /** {@inheritDoc} */ @SuppressWarnings("unchecked") @Override public Vector listarFicheros() throws ServiceException { Session session = null; ChannelSftp channelSftp = null; Channel channel = null; Vector vFicheros = new Vector(); session = conectar(); if (session.isConnected()) { try { channel = session.openChannel("sftp"); channel.connect(); channelSftp = (ChannelSftp) channel; vFicheros = channelSftp.ls(dirRemoto); } catch (JSchException e) { throw new ServiceException(e); } catch (SftpException e) { throw new ServiceException(e); } finally { session.disconnect(); } } return vFicheros; } . . . 11 de 20 Framework Atlas Librería SFTP 4.1.3. Definir servicio de sftp en applicationContext-services.xml Publicamos nuestro servicio en el contexto, inyectándole la dependencia al servicio de envío propio de Spring y la plantilla. applicationContext-services.xml <bean id="sftpService" class="atlas.sftp.services.SftpServiceImpl"> <property name="host" value="${sftp.host}"/> <property name="puerto" value="${sftp.puerto}"/> <property name="usuario" value="${sftp.usuario}"/> <property name="password" value="${sftp.clave}"/> <property name="dirDescarga" value="${sftp.dirDescarga}"/> <property name="dirRemoto" value="${sftp.dirRemoto}"/> </bean> NOTA Con la implementación de la interfaz y esta configuración ya podemos hacer uso de nuestro servicio de envío desde cualquiera de nuestras clases de negocio gestionadas por Spring. A continuación mostraremos un ejemplo de uso del servicio a través de una página JSF. Si ya se tiene claro cómo utilizarlo (igual que el resto de servicios Spring) se puede dar por finalizado el manual. El siguiente ejemplo ha sido extraído de la aplicación de ejemplo de integración*. Aplicación de ejemplo de integración Aplicación de ejemplo creada para mostrar la integración con los diferentes servicios Atlas Url de acceso (usuario_ok/usuario_ok) Código fuente 12 de 20 Framework Atlas Librería SFTP 4.2. Crear fachada Como se explica en la normativa, las páginas JSF interactúan con los servicios a través de una fachada. Así pues, para nuestro ejemplo, creamos la fachada SftpFacade (interfaz e implementación) para que llame a nuestro servicio SftpService. 4.2.1. Crear interfaz de la fachada SftpFacade.java /** * Esta interfaz representa las operaciones * de la fachada para SFTP. * @author ICM * @version 1.0. */ public interface SftpFacade { /** * Método que obtiene un listado de ficheros del servidor SFTP * @return Vector listado de ficheros del directorio remoto * @throws ServiceException error en la invocación */ @SuppressWarnings("unchecked") Vector listarFicheros() throws ServiceException; /** * Método que permite descargar un fichero que se encuentra * en el SFTP a un directorio. * @param fichero el fichero que se va a descargar * @throws ServiceException error en la invocación */ void descargarFichero(String fichero) throws ServiceException; /** * Método que permite eliminar un fichero del SFTP * @param fichero el fichero a eliminar * @throws ServiceException ex */ void eliminarFichero(String fichero) throws ServiceException; /** * Método que permite subir un fichero al SFTP * @param nombreFichero el nombre del fichero * @param is inputstream del fichero * @throws ServiceException error en la invocación */ void subirFichero(InputStream is, String nombreFichero) throws ServiceException; } 13 de 20 Framework Atlas Librería SFTP 4.2.2. Crear implementación de la fachada SftpFacadeImpl.java /** * Esta clase representa la fachada para sftp. * @author ICM * @version 1.0. */ @Service public class SftpFacadeImpl implements SftpFacade { /** Servicio de sftp */ private SftpService sftpService; /** {@inheritDoc} */ @SuppressWarnings("unchecked") @Override public Vector listarFicheros() throws ServiceException { return this.sftpService.listarFicheros(); } /** {@inheritDoc} */ @Override public void descargarFichero(String fichero) throws ServiceException { this.sftpService.descargarFichero(fichero); } /** {@inheritDoc} */ @Override public void eliminarFichero(String fichero) throws ServiceException { this.sftpService.eliminarFichero(fichero); } /** {@inheritDoc} */ @Override public void subirFichero(InputStream is, String nombreFichero) throws ServiceException { this.sftpService.subirFichero(is, nombreFichero); } /** * @param sftpService the sftpService to set */ public void setSftpService(SftpService sftpService) { this.sftpService = sftpService; } } 14 de 20 Framework Atlas Librería SFTP 4.2.3. Definir fachada en applicationContext-services.xml Definir y configurar la fachada, sftpFacade, para que haga uso de nuestro servicio de sftp. applicationContext-services.xml <bean id="sftpFacade" class="atlas.sftp.services.facade.SftpFacadeImpl"> <description> Bean que representa la fachada por la cual acceder a los servicios para SFTP </description> <property name="sftpService" ref="sftpService" /> </bean> 4.3. Crear presentación JSF 4.3.1. Crear backing bean Creamos un bean JSF que realiza la acción de listar ficheros del SFTP. Esta clase hace uso del servicio de sftp a través de la fachada recién creada. SftpFormBean.java 15 de 20 Framework Atlas Librería SFTP /** * The Class SftpFormBean. * @author ICM */ public class SftpFormBean extends BaseBean { /** * La fachada */ @ManagedProperty(value = "#{sftpFacade}") private SftpFacade sftpFacade; /** * El fichero seleccionado. */ private String fichero; /** * Método que sirve para listar los fichero del directorio * remoto del SFTP. */ @SuppressWarnings("unchecked") public void listarFicheros() { try { Vector vFicheros = sftpFacade.listarFicheros(); agregarFicheros(vFicheros); } catch (ServiceException e) { AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "sftp.listar.error"); } finally { } } /** * Método que sirve para agregar ficheros que tengan extensiones permitidas * al componente select. * @param vFicheros Lista de ficheros. */ @SuppressWarnings("unchecked") private void agregarFicheros(Vector vFicheros) { ficheros = new ArrayList<SelectItem>(); int numeroFicheros = vFicheros.size(); for (int ii = 0; ii < numeroFicheros; ii++) { Object obj = vFicheros.elementAt(ii); if (obj instanceof LsEntry) { String nombreFichero = ((LsEntry) obj).getFilename(); agregarSelectItem(nombreFichero); } } } /** * Método que permite agregar un * elemento a selectitem * @param nombreFichero nombre del fichero */ private void agregarSelectItem(String nombreFichero) { ficheros.add(new SelectItem(nombreFichero, nombreFichero)); } /** NOTA: faltan los getters y setters de los atributos */ } 16 de 20 Framework Atlas Librería SFTP 4.3.2. Crear página JSF Por simplicidad, sólo mostramos el botón y el componente h:selectOneListBox donde se mostrarán los ficheros del servidor SFTP. Como se ha indicado anteriormente, todo el código de la aplicación está disponible a través de la siguiente dirección: Código fuente de la aplicación de ejemplo de integración de servicios Atlas sftpSample.xhtml . . . <div class="botonera_izquierda"> <a4j:commandLink id="listar" value="Listar ficheros de SFTP" styleClass="botonAplicacionTXT" render="listaFicheros" action="#{sftpFormBean.listarFicheros}"> <h:graphicImage value="/img/ico_nuevo.gif" alt="#{bundle['lv.enviar']}" /> </a4j:commandLink> </div> <div class="space2"/> <div class="space2"/> <h:panelGrid columns="1"> <h:selectOneListbox id="listaFicheros" value="#{sftpFormBean.fichero}" size="4" style="width: 230px;"> <f:selectItems value="#{sftpFormBean.ficheros}" /> </h:selectOneListbox </h:panelGrid> . . . 17 de 20 Framework Atlas Librería SFTP 5. ENLACES RELACIONADOS Producto URL Ajax4JSF http://www.jboss.org/jbossrichfaces/ Commons Configurations http://commons.apache.org/configuration/ JSF http://java.sun.com/javaee/javaserverfaces/ MyFaces Core http://myfaces.apache.org/ RichFaces http://www.jboss.org/jbossrichfaces/ Spring http://www.springframework.org/ Atlas Integración http://intranet.madrid.org/arquitecturasw/desarrollos-atlas/integracion 18 de 20 Framework Atlas Librería SFTP 6. ANEXOS 6.1. Instalación y configuración de Servidor SSH FTP Para instalar el servidor SFTP y poder usarlo como servidor de pruebas, debemos descargarlo de http://www.freesshd.com/?ctt=download. Seguir los pasos de instalación normalmente. 6.1.1. Crear usuario del Servidor SSH FTP Primero deberemos crear un usuario para que nuestra aplicación web pueda conectarse al servidor mediante este usuario, para ello debemos ejecutar la aplicación haciendo doble click sobre su icono El servidor empezara como un icono en la barra derecha inferior de Windows como se aprecia en la figura: Hacer click derecho y luego hacer click en el menú “Settings…” para abrir la pantalla de configuración del servidor. Ir a la pestaña “Users”, hacer click en el botón “Add”, en la nueva ventana ingresar los datos del usuario: Login: Este será equivalente al valor del campo sftp.usuario que hemos indicado en el fichero environment.properties. Authorization: Seleccionar el valor “Password stored as SHA1 hash” Password: ingresar el password para este usuario (recordar que este valor tendremos que ingresarlo en la página http://intranet.madrid.org/arquitecturasw/desarrollos-atlas/utilidades/encriptacion y el valor devuelto se debe ingresar en campo sftp.clave del fichero environment.properties). User can use: Marcar la opción SFTP. Hacer click en el botón “Aceptar” para crear el usuario, no debe quedar una pantalla como la siguiente: 19 de 20 Framework Atlas Librería SFTP 6.1.2. Establecer directorio del Servidor SSH FTP Para establecer el directorio debemos ir a la pestaña “SFTP”, ahí ubicaremos un directorio que será nuestro directorio por defecto cuando un usuario se conecte a nuestro servidor. 6.1.3. Establecer puerto del Servidor SSH FTP Para establecer el puerto debemos ir a la pestaña “SSH”, ahí indicaremos el puerto de nuestro servidor SFTP, en este ejemplo es 22 (este valor se corresponde con el campo sftp.puerto del fichero environment.properties), dejar los demás valores de esta pestaña como están. 6.1.4. Iniciar servicio SSH del Servidor. Para iniciar el servicio SSH del servidor debemos ir a la pestaña “Server status” y hacer click en el aspa correspondiente al servicio SSH de tal forma que esta pestaña quede como la que se muestra a continuación: 20 de 20