Pasar al contenido principal

Guía del programador

Estas son cosas que sólo un programador que pretende trabajar conERDDAP'sJavalas clases necesitan saberlo.

Obtener el código fuente​

 

  • Via Source Code on GitHub El código fuente de versiones públicas recientes y versiones en desarrollo también está disponible a través deGitHub. Por favor lea elWikipara ese proyecto. Si desea modificar el código fuente (y posiblemente los cambios incorporados en la normaERDDAP™distribución) , este es el enfoque recomendado.

ERDDAP™dependencias​

ERDDAP™utiliza Maven para cargar dependencias de código, así como algunos archivos de referencia estáticos (WEB-INF/ref) . Esto se hace para evitar almacenar muchos archivos grandes en el repositorio. Puede utilizar mvn compil y que buscará las dependencias y archivos de referencia. También puede utilizar mvn package para generar un archivo de guerra. Puede descargar manualmente los archivos ref:

  • etopo1\_ice\_g\_i2.zipy descifrarlo en /WEB-INF/ref/ .

  • \_files.zipy descifrarlo en /WEB-INF/ref/ .

  • erddapContent.zip (versión 1.0.0, 20333 bytes, MD5=2B8D2A5AE5ED73E3A42B529C168C60B5, de fecha 2024-10-14) y deshacerlo en tomcat, creando_tomcat_/content/erddap.

NOTA: Por defecto Maven caché estática referencia y prueba descargas de archivos de datos y sólo extraerlos cuando se descarga una nueva versión. Para evitar la descarga por completo, puede establecer las propiedades skipResourceDownload y/o skipTestResourceDownload a Maven (e.g. mvn -DskipResourceDownload package ) . Para la extracción de fuerza, establece -Ddownload.unpack=true y -Ddownload.unpackWhenChanged=false.

  • ERDDAP™y sus subcomponentes tienen una fuente abierta muy liberallicencias, para que pueda utilizar y modificar el código fuente para cualquier propósito, con fines de lucro o sin fines de lucro. Note queERDDAP™y muchos subcomponentes tienen licencias que requieren que usted reconozca la fuente del código que está utilizando. SeeCréditos. Ya sea necesario o no, es sólo una buena forma de reconocer a todos estos contribuyentes.

  • Use el Código para Otros Proyectos

Mientras usted es bienvenido a utilizar partes de laERDDAP™código para otros proyectos, se advierta que el código puede y cambiará. No prometemos apoyar otros usos de nuestro código. Git y GitHub serán sus principales soluciones para tratar con esto - Git le permite fusionar nuestros cambios en sus cambios. Para muchas situaciones donde se puede tentar a usar partes deERDDAP™en su proyecto, creemos que encontrará mucho más fácil de instalar y utilizarERDDAP™como es, y luego escribir otros servicios que utilizanERDDAP's servicios. Puedes configurar tu propioERDDAP™instalación crudamente en una hora o dos. Puedes configurar tu propioERDDAP™instalación de forma pulida en unos pocos días (dependiendo del número y la complejidad de sus conjuntos de datos) . Pero hackear partes deERDDAP™para su propio proyecto es probable que lleve semanas (y meses para atrapar sutilezas) y usted perderá la capacidad de incorporar cambios y correcciones de errores de subsiguientesERDDAP™liberaciones. Nosotros (Obviamente) pensar que hay muchos beneficios para usarERDDAP™como es y haciendo suERDDAP™instalación accesible al público. Sin embargo, en algunas circunstancias, es posible que no desee hacer suERDDAP™instalación accesible al público. Entonces, su servicio puede acceder y utilizar su privadoERDDAP™y sus clientes no necesitan saberERDDAP™.

Medio camino​

O, hay otro enfoque que usted puede encontrar útil que está a la mitad entre el devenir enERDDAP's código y usoERDDAP™como un servicio web independiente: En la clase EDD, hay un método estático que le permite hacer una instancia de un conjunto de datos (basado en la especificación endatasets.xml) : unodeDataset Xml (Pendiente tDatasetID) Devuelve una instancia de un EDDTable oEDDGridDataset. Dada esa instancia, puedes llamar makeNewFileForDapQuery (Usuario de contactosDapQuery, String dir, archivo StringName, archivo String TipoName) `para indicar la instancia para hacer un archivo de datos, de un fichero específicoType, con los resultados de una consulta de usuario. Así, esta es una manera sencilla de usarERDDAP's métodos para solicitar datos y obtener un archivo en respuesta, así como un cliente utilizaría elERDDAP™aplicación web. Pero este enfoque funciona dentro de tuJavaprograma y aprueba la necesidad de un servidor de aplicaciones como Tomcat. Utilizamos este enfoque para muchas de las pruebas unitarias de EDDTable yEDDGridsubclases, para que puedas ver ejemplos de esto en el código fuente para todas esas clases.

Development​

  • Hay configuraciones paraJettyyDockeren GitHub, aunque se espera que las liberaciones corran en Tomcat.

  • Facultativo : ConfiguraciónERDDAP™en Tomcat DesdeERDDAP™está destinado principalmente a ser un servlet corriendo en Tomcat, recomendamos encarecidamente que siga el estándarInstrucciones de instalaciónpara instalar Tomcat, y luego instalarERDDAP™en el directorio webapps de Tomcat. Entre otras cosas,ERDDAP™fue diseñado para ser instalado en la estructura del directorio de Tomcat y espera que Tomcat proporcione algunos archivos .jar.

  • ERDDAP™no requiere un IDE específico (Chris utiliza principalmente código Visual Studio, Bob usó EditPlus) . No utilizamos Eclipse, Ant, etc.; ni ofrecemosERDDAP- apoyo relacionado con ellos. El proyecto utiliza Maven.

  • Utilizamos un archivo de lotes que elimina todos los archivos de clase . en el árbol fuente para asegurar que tenemos una compilación limpia (con javac) .

  • Actualmente utilizamos el javac jdk-21.0.3+9 de Adoptium para compilar gov.noaa.pfeg.coastwatch.TestAll (tiene enlaces a algunas clases que no se compilan de otra manera) y hacer las pruebas. Por razones de seguridad, es casi siempre mejor utilizar las últimas versiones deJava21 y Tomcat 10.

    • Cuando ejecutamos javac o java, el directorio actual es tomcat/webapps/erddap/WEB-INF .

    • Nuestra clase de javac y java es clases;././././lib/servlet-api.jar;lib/*

    • Así que tu línea de comando javac será algo como " clases " javac -encoding UTF-8 -cp;././././lib/servlet-api.jar;lib/* clases/gov/noaa/pfel/coastwatch/TestAll.java "

    • Y tu línea de comando de java será algo como " clases de lava -cp;././././lib/servlet-api.jar;lib/* -Xmx4000M -Xms4000M clases/gov/noaa/pfel/coastwatch/TestAll Opcional: se puede añadir -verbose:gc`, que diceJavapara imprimir estadísticas de recogida de basura.

    • Si prueba Todo compila, todoERDDAP™se han recopilado las necesidades. Algunas clases son compiladas que no son necesarias paraERDDAP™. Si compilar TestAll tiene éxito pero no compila alguna clase, esa clase no es necesaria. (Hay algunas clases inacabadas o no utilizadas.)

  • En algunos casos, utilizamos código fuente de terceros en lugar de archivos .jar (en particularDODS) y los han modificado ligeramente para evitar problemas compilando conJava21. A menudo hemos hecho otras pequeñas modificaciones (en particularDODS) por otras razones.

  • La mayoría de las clases tienen métodos de prueba en su archivo src/test asociado. Puede ejecutar las pruebas JUnit con el comando mvn test. Esto descargará varios archivos zip de datos que las pruebas se basan en la última versión deERDDAP/erddap Prueba.   NOTA: Maven caches descarga, pero descifrará los archivos descargados en cada ejecución, que toma tiempo. Para evitar la descarga y descifrar archivos de datos de prueba, puede especificar la propiedad skipTestResourceDownload a Maven (e.g. mvn -DskipTestResourceDownload package ) .

Clases importantes​

Si quieres ver el código fuente e intentar averiguar cómoERDDAP™funciona, por favor.

  • El código tieneJavaDoc comenta, pero elJavaLos médicos no han sido generados. Siéntete libre de generarlos.

  • Las clases más importantes (incluidos los mencionados a continuación) están dentro de gov/noaa/pfel/erddap.

  • ElERDDAP™la clase tiene los métodos más altos. Se extiende HttpServlet.

  • ERDDAP™solicitudes a casos de subclasesEDDGrido EDDTable, que representan conjuntos de datos individuales.

  • EDStatic tiene la mayor parte de la información estática y la configuración (por ejemplo, desde los archivos setup.xml y messages.xml) y ofrece servicios estáticos (por ejemplo, envío de correos electrónicos) .

  • EDDGridy subclases EDDTable analizan la solicitud, obtener datos de métodos específicos de subclase, luego formatear los datos para la respuesta.

  • EDDGridsubclases empujar datos a GridDataAccessor (el contenedor de datos interno para datos redondeados) .

  • Las subclases EDDTable empujan los datos a las subclas de TableWriter, que escriben datos a un tipo de archivo específico en la marcha.

  • Otras clases (por ejemplo, clases de bajo nivel) son también importantes, pero es menos probable que estés trabajando para cambiarlos.  

Contribuciones del Código​

  • Problemas de GitHub Si desea contribuir, pero no tiene un proyecto, vea la lista deProblemas de GitHub, muchos de los cuales son proyectos que podrías realizar. Si desea trabajar en un problema, por favor asignárselo a usted mismo para indicar a otros que está trabajando en él. La cuestión de GitHub es el mejor lugar para debatir cualquier pregunta sobre cómo proceder con la labor sobre esa cuestión.

  • Si el cambio que desea hacer es uno de los siguientes casos comunes, por favor cree unCuestión de GitHubindicando el cambio que pretende hacer. Luego, una vez que el cambio esté completo, haga una solicitud de tirada para solicitar la fusión. Los cambios comunes incluyen:

    • Quieres escribir otra subclase deEDDGrido EDDTable para manejar otro tipo de fuente de datos. Si es así, le recomendamos que encuentre la subclase existente más cercana y utilice ese código como punto de partida.

    • Quieres escribir otro método saveAs_FileType_. Si es así, te recomendamos que encuentres el método SaveAs_FileType_ más cercanoEDDGrido EDDTable y utilizar ese código como punto de partida.

Esas situaciones tienen la ventaja de que el código que escribes es autocontenido. No necesitarás saber todos los detallesERDDAPEs interno. Y será fácil para nosotros incorporar su código enERDDAP. Tenga en cuenta que si envía código, la licencia necesitará compatible con elERDDAP™ licencia (por ejemplo,Apache,BSDoMIT-X) . Listaremos su contribución en laacreedores.

  • Si usted tiene una característica no cubierta arriba que le gustaría añadir aERDDAP, se recomienda crear primero un hilo de discusión en elDiscusiones GitHub. Para características/cambios significativos, la Junta Técnica los discutirá y decidirá si aprobará agregarlo aERDDAP™.

A juzgar por sus contribuciones al Código​

Si desea enviar código u otros cambios a incluir enERDDAPEso es genial. Su contribución debe cumplir ciertos criterios para ser aceptada. Si sigue las pautas siguientes, aumenta considerablemente las posibilidades de que se acepte su contribución.  

  • ElERDDAP™proyecto es gestionado por un NATD (NOAADesignado Director Técnico) con aportaciones de una Junta Técnica. De 2007 (el comienzo delERDDAP) hasta 2022, ese era Bob Simons (también el Fundador-Leader) . A partir de enero de 2023, es Chris John. Basically, the NATD is responsible forERDDAP, así que tiene la palabra final sobre las decisiones sobreERDDAP™código, en particular sobre el diseño y si se aceptará o no una solicitud de tirada determinada. Tiene que ser así en parte por razones de eficiencia (funciona genial para Linus Torvalds y Linux) y en parte por razones de seguridad: Alguien tiene que decirle a la gente de seguridad de TI que se hace responsable de la seguridad e integridad del código.  

  • La NATD no garantiza que acepte su código. Si un proyecto no funciona tan bien como esperábamos y si no se puede salvar, la NATD no incluirá el proyecto en el proyectoERDDAP™distribución. Por favor no te sientas mal. A veces los proyectos no funcionan tan bien como esperaban. Sucede a todos los desarrolladores de software. Si sigue las pautas siguientes, aumenta considerablemente sus posibilidades de éxito.  

  • Es mejor si los cambios son de interés general y utilidad. Si el código es específico para su organización, probablemente sea mejor mantener una rama separada deERDDAP™para su uso. Axiom hace esto. Afortunadamente, Git hace esto fácil de hacer. La NATD quiere mantener una visión coherente paraERDDAP, no permitir que se convierta en un proyecto de fregadero de cocina donde todos agregan una característica personalizada para su proyecto.  

  • Seguir elJavaConvenios de Código. En general, su código debe ser de buena calidad y debe seguir el originalJavaCode Conventions: poner archivos .class en el lugar adecuado en la estructura del directorio, dar a los archivos .class un nombre apropiado, incluirJavaDoc comentarios, incluyen //comentarios al inicio de cada párrafo del código, indent con 4 espacios (no pestaña) , evite las líneas √80 caracteres, etc. Las convenciones cambian y el código fuente no siempre está al día. Cuando en duda, coincida con el código de las convenciones y no con el código existente.

  • Utilice la clase descriptiva, el método y los nombres variables. Eso hace que el código sea más fácil para que otros lean.  

  • Evite código de fantasía. A largo plazo, usted u otra gente tendrá que averiguar el código para mantenerlo. Así que por favor use métodos de codificación simples que son así más fáciles para otros (incluido en el futuro) para averiguarlo. Obviamente, si hay una ventaja real para usar algo de fantasíaJavaprogramar característica, utilizarlo, pero documentar ampliamente lo que hiciste, por qué, y cómo funciona.  

  • Trabaja con la Junta Técnica antes de comenzar. Si esperas que tus cambios de código se introduzcan enERDDAP™, La Junta Técnica definitivamente querrá hablar de lo que vas a hacer y cómo vas a hacerlo antes de hacer cualquier cambio en el código. De esa manera, podemos evitar que hagas cambios que la NATD, al final, no acepta. Cuando usted está haciendo el trabajo, la NATD y la Junta Técnica están dispuestos a responder preguntas para ayudarle a averiguar el código existente y (general) cómo abordar su proyecto.  

  • Trabajar independientemente (tanto como sea posible) después de empezar. En contraste con lo anterior "Trabajar con la Junta Técnica", después de comenzar el proyecto, la NATD le anima a trabajar lo más independiente posible. Si la NATD tiene que decirle casi todo y responder un montón de preguntas (especialmente los que podría haber respondido leyendo la documentación o el código) , entonces sus esfuerzos no son un ahorro de tiempo para la NATD y también puede hacer el trabajo ellos mismos. Es elMeses del Hombre Místicoproblema. Por supuesto, todavía debemos comunicarnos. Sería genial ver periódicamente su trabajo en progreso para asegurarse de que el proyecto está en marcha. Pero cuanto más puedas trabajar independientemente (después de que la Junta Técnica convenga en la tarea que se está realizando y en el enfoque general) Mejor.  

  • Evite los errores. Si un error no es atrapado antes de una liberación, causa problemas para los usuarios (al mejor) , devuelve la información incorrecta (en el peor) , es una mancha enERDDAP's reputación, y persistirá en fuera de la fechaERDDAP™instalaciones durante años. Trabajar muy duro para evitar errores. Parte de esto es escribir código limpio (así que es más fácil ver problemas) . Parte de esto es escribir pruebas de unidad. Parte de esto es una actitud constante de evitar errores cuando escribe código. No hagas que la NATD se arrepienta de agregar tu código aERDDAP™.  

  • Escribe una prueba o prueba de unidad. Para nuevo código, debe escribir pruebas JUnit en un archivo de prueba. Por favor escriba al menos un método de prueba individual que prueba a fondo el código que escribe y lo agregue al archivo de prueba JUnit de clase para que se ejecute automáticamente. Dependencia (y conexas) las pruebas son una de las mejores maneras de atrapar errores, inicialmente, y a largo plazo (como otras cosas cambianERDDAP™) . Como Bob dijo, "Las pruebas de la unidad son lo que me deja dormir por la noche."  

  • Haga que sea fácil para la NATD entender y aceptar los cambios en su solicitud de tirada. Parte de eso es escribir un método de prueba de unidad (s) . Parte de eso está limitando sus cambios a una sección de código (o una clase) si es posible. La NATD no aceptará ninguna solicitud de tirada con cientos de cambios a lo largo del código. La NATD dice a las personas de seguridad de TI que se hace responsable de la seguridad e integridad del código. Si hay demasiados cambios o son demasiado difíciles de averiguar, entonces es demasiado difícil verificar los cambios son correctos y no introducir errores o problemas de seguridad.  

  • Mantenlo sencillo. Un buen tema general para su código es: Mantenlo sencillo. Código simple es fácil para otros (incluido en el futuro) para leer y mantener. Es fácil para la NATD entender y así aceptar.  

  • Asuma la responsabilidad a largo plazo por su código. A largo plazo, es mejor que asuman la responsabilidad constante de mantener su código y responder preguntas al respecto (por ejemplo, en elERDDAP™Google Group) . Como señalan algunos autores, el código es una responsabilidad así como un activo. Si un error es descubierto en el futuro, es mejor si lo arreglas porque nadie sabe tu código mejor que tú. (también para que haya un incentivo para evitar errores en primer lugar) . La NATD no está pidiendo un compromiso firme para proporcionar mantenimiento continuo. La NATD está diciendo que hacer el mantenimiento será muy apreciado.