Salta al contenuto principale

Guida del programmatore

Queste sono cose che solo un programmatore che intende lavorare conERDDAP'Javale classi devono saperlo.

Ottenere il codice sorgente​

 

  • Via Codice sorgente su GitHub Il codice sorgente per le recenti versioni pubbliche e le versioni in fase di sviluppo è disponibile anche tramiteGitHub. Si prega di leggere ilWikiper quel progetto. Se si desidera modificare il codice sorgente (e possibilmente hanno i cambiamenti incorporati nello standardERDDAP™distribuzione) , questo è l'approccio raccomandato.

ERDDAP™dipendenze​

ERDDAP™utilizza Maven per caricare dipendenze di codice e alcuni file di riferimento statici (WEB-INF/ref) . Questo è fatto per evitare di memorizzare molti file di grandi dimensioni nel repository. È possibile utilizzare mvn compila e che otterrà le dipendenze e ref file. È inoltre possibile utilizzare mvn package per generare un file di guerra. È possibile scaricare manualmente i file ref:

  • etopo1.zipe spostarlo in /WEB-INF/ref/ .

  • ref\_files.zipe spostarlo in /WEB-INF/ref/ .

  • erddapContent.zip (versione 1.0.0, 20333 byte, MD5=2B8D2A5AE5ED73E3A42B529C168C60B5, datata 2024-10-14) e szip in tomcat, creando_tomcat_/content/erddap.

NOTA: Per impostazione predefinita, Maven cacherà i download dell'archivio dati di riferimento statico e di prova e li estrarra solo quando viene scaricata una nuova versione. Per saltare il download del tutto, è possibile impostare le proprietà skipResourceDownload e/o skipTestResourceDownload a Maven (e.g. mvn -DskipResourceScarica il pacchetto #) . Per forzare l'estrazione, impostare -Ddownload.unpack=truee-Ddownload.unpackWhenChanged=false`.

  • ERDDAP™e i suoi subcomponenti sono molto liberali, open sourcelicenze, in modo da poter utilizzare e modificare il codice sorgente per qualsiasi scopo, per-profit o no-profit. Nota:ERDDAP™e molti subcomponenti hanno licenze che richiedono di riconoscere la fonte del codice che si sta utilizzando. VediCrediti. Se richiesto o meno, è solo una buona forma per riconoscere tutti questi collaboratori.

  • Utilizzare il codice per altri progetti

Mentre siete invitati a utilizzare parti delERDDAP™codice per altri progetti, essere avvertito che il codice può e cambierà. Non promettiamo di sostenere altri usi del nostro codice. Git e GitHub saranno le vostre soluzioni principali per affrontare questo -- Git vi permette di unire i nostri cambiamenti nei vostri cambiamenti. Per molte situazioni in cui si potrebbe essere tentati di utilizzare parti diERDDAP™nel vostro progetto, pensiamo che troverete molto più facile da installare e utilizzareERDDAP™come è, e poi scrivere altri servizi che utilizzanoERDDAPI servizi. Si può impostare il proprioERDDAP™installazione grezzo in un'ora o due. Si può impostare il proprioERDDAP™installazione in modo lucido in pochi giorni (a seconda del numero e della complessità dei tuoi set di dati) . Ma...ERDDAP™per il tuo progetto è probabile che ci vorranno settimane (e mesi per catturare sottigliezze) e si perde la capacità di incorporare modifiche e correzioni di bug da successiviERDDAP™rilascia. Noi (ovviamente) pensare che ci sono molti vantaggi per l'utilizzoERDDAP™come è e rendere il vostroERDDAP™installazione pubblicamente accessibile. Tuttavia, in alcune circostanze, potrebbe non voler rendere il vostroERDDAP™installazione pubblicamente accessibile. Poi, il vostro servizio può accedere e utilizzare il vostro privatoERDDAP™e i tuoi clienti non hanno bisogno di sapereERDDAP™.

A metà strada​

O, c'è un altro approccio che si può trovare utile che è a metà strada tra delving inERDDAPil codice e l'utilizzoERDDAP™come servizio web stand-alone: Nella classe EDD, c'è un metodo statico che consente di fare un'istanza di un set di dati (in base alle specifichedatasets.xml) : "Dataset" Xml (String tDatasetID) Restituisce un'istanza di un EDDTable oEDDGridDataset. Data l'istanza, puoi chiamare\\ #MakeNewFileForDapQuery # (String userDapQuery, String dir, String fileName, String file Tipologia) per indicare l'istanza di fare un file di dati, di un file specificoTipo, con i risultati di una query dell'utente. Così, questo è un modo semplice per usareERDDAP's metodi per richiedere i dati e ottenere un file in risposta, proprio come un client userebbeERDDAP™applicazione web. Ma questo approccio funziona nel tuoJavaprogramma e bypassa la necessità di un server di applicazione come Tomcat. Usiamo questo approccio per molti dei test di unità di EDDTable eEDDGridsottoclassi, in modo da poter vedere esempi di questo nel codice sorgente per tutte quelle classi.

Ambiente​

  • Ci sono configurazioni perJettyeDockera GitHub, anche se le versioni sono previste per eseguire in Tomcat.

  • Facoltativo : ImpostazioneERDDAP™in Tomcat\ DaERDDAP™è principalmente destinato ad essere un servlet in esecuzione in Tomcat, si consiglia vivamente di seguire lo standardistruzioni di installazioneper installare Tomcat, e poi installareERDDAP™nella directory webapps di Tomcat. Tra le altre cose,ERDDAP™è stato progettato per essere installato nella struttura di directory di Tomcat e si aspetta Tomcat per fornire alcuni file .jar.

  • ERDDAP™non richiede un IDE specifico (Chris utilizza principalmente Visual Studio Code, Bob utilizzato EditPlus) . Non usiamo Eclipse, Ant, ecc; né offriamoERDDAP- il supporto per loro. Il progetto utilizza Maven.

  • Usiamo un file batch che elimina tutti i file .class nell'albero di origine per garantire che abbiamo una compilazione pulita (con javac) .

  • Usiamo attualmente il javac di Adoptium jdk-21.0.3+9 per compilare gov.noaa.pfeg.coastwatch.TestAll (ha collegamenti a alcune classi che non sarebbero compilati altrimenti) e eseguire i test. Per motivi di sicurezza, è quasi sempre meglio utilizzare le ultime versioni diJava21 e Tomcat 10.

    • Quando eseguiamo javac o java, la directory corrente è tomcat/webapps/erddap/WEB-INF .

    • Il nostro percorso di javac e java è classi;././././lib/servlet-api.jar;lib/*

    • Quindi la vostra linea di comando javac sarà qualcosa di simile\ javac -codifica classi UTF-8 -cp;./././././lib/servlet-api.jar;lib/* classi/gov/noa/pfel/coastwatch/TestAll.java

    • E la vostra linea di comando java sarà qualcosa di simile\ java -cp class;./././././lib/servlet-api.jar;lib/* -Xmx4000M -Xms4000M classi/gov/noa/pfel/coastwatch/TestAll Opzionale: è possibile aggiungere -verbose:gc, che diceJavaper stampare statistiche di raccolta rifiuti.

    • Se prova Tutte le compilazioni, tuttoERDDAP™i bisogni sono stati compilati. Alcune classi sono compilate che non sono necessarie perERDDAP™. Se la compilazione di TestAll riesce, ma non compila una certa classe, quella classe non è necessaria. (Ci sono alcune classi incompiute/non utilizzate.)

  • In alcuni casi, utilizziamo il codice sorgente di terze parti invece dei file .jar (in particolareDODS) e li hanno modificati leggermente per evitare problemi di compilazioneJava21. Abbiamo spesso fatto altre piccole modifiche (in particolareDODS) per altri motivi.

  • La maggior parte delle classi hanno metodi di test nel loro file src/test associato. È possibile eseguire i test JUnit con il comando mvn test. Questo scaricherà diversi file zip di dati che i test si basano sull'ultima versione diERDDAPTraduzione: Test.   NOTA: Maven caches downloads ma rimuoverà gli archivi scaricati su ogni esecuzione, che richiede tempo. Per saltare il download e decomprimere archivi di dati di prova, è possibile specificare la proprietà skipTestResourceDownload a Maven (e.g. `mvn -DskipTestResourceScarica il pacchetto #) .

Classi importanti​

Se si desidera guardare il codice sorgente e cercare di capire comeERDDAP™lavori, per favore.

  • Il codice haJavaDoc commenta, ma ilJavaI dottori non sono stati generati. Sentitevi liberi di generarli.

  • Le classi più importanti (compresi quelli indicati di seguito) sono all'interno di gov/noaa/pfel/erddap.

  • TheERDDAP™classe ha i metodi di livello più alto. Si estende HttpServlet.

  • ERDDAP™passa richieste a istanze di sottoclassi diEDDGrido EDDTable, che rappresentano singoli set di dati.

  • EDStatic ha la maggior parte delle informazioni e delle impostazioni statiche (ad esempio, dai file setup.xml e message.xml) e offre servizi statici (ad esempio, inviando e-mail) .

  • EDDGride sottoclassi EDDTable parse la richiesta, ottenere i dati da metodi specifici di sottoclasse, quindi formattare i dati per la risposta.

  • EDDGridsottoclassi spingono i dati in GridDataAccessor (il contenitore dati interno per i dati grigliati) .

  • Le sottoclassi EDDTable spingono i dati nelle sottoclassi TableWriter, che scrivono i dati a un tipo di file specifico on-the-fly.

  • Altre classi (ad esempio, classi di basso livello) sono anche importanti, ma è meno probabile che lavorerai per cambiarli.  

Contributi del codice​

  • Problemi GitHub Se vuoi contribuire ma non hai un progetto, vedi l'elencoProblemi GitHub, molti dei quali sono progetti che si potrebbe prendere su. Se si desidera lavorare su un problema, si prega di assegnarlo a te stesso per indicare agli altri che si sta lavorando su di esso. Il problema GitHub è il posto migliore per discutere qualsiasi domanda per come procedere con il lavoro su quel problema.

  • Se il cambiamento che si desidera fare è uno dei seguenti casi comuni, si prega di creare unProblema GitHubindicando il cambiamento che intende fare. Poi una volta che il cambiamento è completo, fare una richiesta pull per richiedere la fusione. I cambiamenti comuni includono:

    • Vuoi scrivere un'altra sottoclasse diEDDGrido EDDTable per gestire un altro tipo di sorgente dati. Se è così, si consiglia di trovare la sottoclasse esistente più vicina e utilizzare quel codice come punto di partenza.

    • Vuoi scrivere un altro metodo saveAs_FileType_. Se è così, si consiglia di trovare il metodo salvaAs_FileType_ più vicino inEDDGrido EDDTable e utilizzare quel codice come punto di partenza.

Queste situazioni hanno il vantaggio che il codice che scrivi è autocontenuto. Non è necessario conoscere tutti i dettagli diERDDAPE' interno. E sarà facile per noi incorporare il vostro codice inERDDAP. Nota che se si invia il codice, la licenza avrà bisogno di compatibilità con ilERDDAP™ licenza (ad esempio,Apache♪BSDoMIT-X) . Elenceremo il tuo contributo nelcrediti.

  • Se avete una funzione non coperta sopra che si desidera aggiungere aERDDAP, si consiglia prima di creare un filo di discussione nelGitHub Discussioni. Per caratteristiche/cambiamenti significativi il Consiglio Tecnico ne discuterà e deciderà se approvarloERDDAP™.

A giudicare i tuoi contributi al codice​

Se si desidera inviare codice o altre modifiche da includereERDDAPE' fantastico. Il vostro contributo deve soddisfare determinati criteri per essere accettato. Se si seguono le linee guida qui sotto, si aumenta notevolmente le probabilità del vostro contributo essere accettato.  

  • TheERDDAP™il progetto è gestito da un NATD (NOAANominato Direttore Tecnico) con ingresso da un Technical Board. Dal 2007 (l'inizio delERDDAP) nel 2022, quello era Bob Simons (anche il Fondatore-Leader) . A partire dal gennaio 2023, quello è Chris John. Fondamentalmente, il NATD è responsabile perERDDAP, così s/he ha la parola finale sulle decisioniERDDAP™codice, in particolare sulla progettazione e se una data richiesta pull sarà accettata o meno. Deve essere in questo modo in parte per motivi di efficienza (funziona benissimo per Linus Torvalds e Linux) e in parte per motivi di sicurezza: Qualcuno deve dire alle persone di sicurezza IT che si assume la responsabilità per la sicurezza e l'integrità del codice.  

  • Il NATD non garantisce che accetterà il tuo codice. Se un progetto non funziona così come avevamo sperato e se non può essere recuperato, il NATD non includerà il progetto nelERDDAP™distribuzione. Ti prego, non sentirti in colpa. A volte i progetti non funzionano così come sperato. Succede a tutti gli sviluppatori di software. Se si seguono le linee guida qui sotto, si aumenta notevolmente le probabilità di successo.  

  • E 'meglio se i cambiamenti sono di interesse generale e utilità. Se il codice è specifico per la vostra organizzazione, è probabilmente meglio mantenere un ramo separato diERDDAP™per il vostro utilizzo. L'assioma lo fa. Per fortuna, Git lo rende facile da fare. Il NATD vuole mantenere una visione coerente perERDDAP, non permettere che diventi un progetto di lavandino della cucina dove tutti aggiungono una caratteristica personalizzata per il loro progetto.  

  • Seguire ilJavaConvenzioni di codice. In generale, il tuo codice dovrebbe essere di buona qualità e dovrebbe seguire l'originaleJavaConvenzioni di codice: mettere i file .class nel posto corretto nella struttura della directory, dare file .class un nome appropriato, includere il correttoJavaDoc commenta, includere //commenti all'inizio di ogni paragrafo di codice, indent con 4 spazi (non scheda) , evitare linee > 80 caratteri, ecc. Le convenzioni cambiano e il codice sorgente non è sempre aggiornato. Quando in dubbio, corrispondere codice alle convenzioni e non codice esistente.

  • Utilizzare la classe descrittiva, il metodo e i nomi variabili. Questo rende il codice più facile per gli altri da leggere.  

  • Evita il codice di fantasia. A lungo termine, voi o altre persone dovranno capire il codice per mantenerlo. Quindi si prega di utilizzare semplici metodi di codifica che sono così più facili per gli altri (incluso in futuro) per capire. Ovviamente, se c'è un vero vantaggio per usare un po 'di fantasiaJavafunzione di programmazione, usarlo, ma documenta ampiamente ciò che hai fatto, perché, e come funziona.  

  • Lavorare con il Technical Board prima di iniziare. Se si spera di ottenere i cambiamenti del codice inERDDAP™, The Technical Board vorrà sicuramente parlare di quello che farai e di come lo farai prima di apportare modifiche al codice. In questo modo, possiamo evitare di fare cambiamenti che il NATD, alla fine, non accetta. Quando si sta facendo il lavoro, il NATD e Technical Board è disposto a rispondere a domande per aiutarti a capire il codice esistente e (globale) come affrontare il vostro progetto.  

  • Lavoro indipendente (quanto più possibile) dopo l'inizio. In contrasto con quanto sopra "Lavorare con il Consiglio Tecnico", dopo aver iniziato il progetto, il NATD ti incoraggia a lavorare il più in modo indipendente possibile. Se il NATD deve dirvi quasi tutto e rispondere a molte domande (soprattutto quelli che avresti potuto rispondere leggendo la documentazione o il codice) , allora i vostri sforzi non sono un risparmio di tempo per il NATD e s / lui potrebbe anche fare il lavoro loro stessi. E' ilMese dell'Uomo Miticoproblema. Naturalmente, dobbiamo ancora comunicare. Sarebbe bello vedere periodicamente il vostro lavoro in corso per assicurarsi che il progetto sia in pista. Ma più si può lavorare indipendentemente (dopo l'accordo del Consiglio tecnico sul compito a portata di mano e sull'approccio generale) Meglio.  

  • Evita gli insetti. Se un bug non viene catturato prima di un rilascio, causa problemi per gli utenti (al meglio) , restituisce le informazioni sbagliate (al peggio) , è un blot suERDDAPla reputazione, e persevererà su out-of-dateERDDAP™impianti per anni. Lavorare molto duramente per evitare bug. Parte di questo è scrivere codice pulito (così è più facile vedere i problemi) . Parte di questo è test unità di scrittura. Parte di questo è un atteggiamento costante di evitare bug quando si scrive codice. Non fare rimpiangere NATD aggiungendo il codice aERDDAP™.  

  • Scrivere un test di unità o test. Per il nuovo codice, si dovrebbe scrivere test JUnit in un file di prova. Si prega di scrivere almeno un metodo di prova individuale che testa a fondo il codice che si scrive e aggiungerlo al file di prova JUnit classe in modo che venga eseguito automaticamente. Unità (e relative) test sono uno dei modi migliori per catturare bug, inizialmente, e nel lungo periodo (come altre cose cambianoERDDAP™) . Come disse Bob: "I test sono ciò che mi fa dormire la notte".  

  • Rendere più facile per il NATD capire e accettare le modifiche nella vostra richiesta pull. Parte di ciò sta scrivendo un metodo di prova unità (#) . Parte di questo sta limitando le modifiche a una sezione del codice (o una classe) se possibile. Il NATD non accetterà alcuna richiesta pull con centinaia di modifiche in tutto il codice. Il NATD dice alle persone di sicurezza IT che si assume la responsabilità per la sicurezza e l'integrità del codice. Se ci sono troppe modifiche o sono troppo difficili da capire, allora è troppo difficile verificare che le modifiche siano corrette e non introdurre bug o problemi di sicurezza.  

  • Tienila semplice. Un buon tema generale per il vostro codice è: mantenere semplice. Il codice semplice è facile per gli altri (incluso in futuro) leggere e mantenere. È facile per il NATD capire e quindi accettare.  

  • Assumere responsabilità a lungo termine per il vostro codice. Nel lungo periodo, è meglio se si assume la responsabilità continua per mantenere il codice e rispondere a domande su di esso (ad esempio, nelERDDAP™Google Group) . Come alcuni autori notano, il codice è una responsabilità così come un bene. Se un bug viene scoperto in futuro, è meglio se si risolve perché nessuno conosce il tuo codice meglio di te (anche in modo che ci sia un incentivo per evitare bug in primo luogo) . Il NATD non chiede un impegno costante per la manutenzione in corso. Il NATD sta solo dicendo che fare la manutenzione sarà molto apprezzato.