Sari la conținutul principal

Ghidul programatorului

Acestea sunt lucruri pe care doar un programator care intenționează să lucreze cuERDDAP'sJavaCursurile trebuie să ştie.

Obținerea codului sursă​

 

  • Prin codul sursă al GitHub Codul sursă pentru versiunile publice recente și versiunile în dezvoltare este de asemenea disponibil prin intermediulGitHub. Vă rugăm să citiţiWikipentru acel proiect. Dacă doriți să modificați codul sursă (și eventual au modificările încorporate în standardERDDAP™distribuţie) Aceasta este abordarea recomandată.

ERDDAP™dependențe​

ERDDAP™folosește Maven pentru a încărca dependențe cod, precum și unele fișiere de referință statice (WEB-INF/REF) . Acest lucru se face pentru a evita stocarea mai multor fișiere mari în depozit. Puteți utiliza Puteți utiliza, de asemenea, pachetul MVN să genereze un fișier de război. Puteți descărca manual fișierele ref:

NOTĂ: În mod implicit, Maven va înregistra referințe statice și va testa descărcarea arhivei datelor și le va extrage numai atunci când o nouă versiune este descărcată. Pentru a sări peste descărcarea în întregime, puteți seta (de ex. ) . Pentru a forţa extracţia, setaţi

  • ERDDAP™şi subcomponentele sale au o sursă foarte liberalălicențe, astfel încât să puteți utiliza și modifica codul sursă pentru orice scop, pentru-profit sau non-profit. Notă:ERDDAP™și multe subcomponente au licențe care necesită să recunoașteți sursa codului pe care îl utilizați. Vezi?Credite. Fie că este necesar sau nu, este doar o formă bună pentru a recunoaște toți acești contribuitori.

  • Utilizarea codului pentru alte proiecte

În timp ce sunteți binevenit să utilizați părți aleERDDAP™cod pentru alte proiecte, fiţi avertizaţi că codul poate şi se va schimba. Nu promitem să sprijinim alte utilizări ale codului nostru. Git şi GitHub vor fi principalele soluţii pentru a face faţă acestei situaţii -- Git vă permite să fuzionaţi modificările noastre cu modificările dumneavoastră. Pentru multe situații în care s-ar putea fi tentat să folosească părți dinERDDAP™în proiectul dumneavoastră, credem că veţi găsi mult mai uşor de instalat şi utilizatERDDAP™așa cum este, și apoi scrie alte servicii care utilizeazăERDDAPServiciile lui. Puteți configura propria taERDDAP™instalarea brută într-o oră sau două. Puteți configura propria taERDDAP™instalare în mod lustruit în câteva zile (în funcție de numărul și complexitatea seturilor de date) . Dar hacking părți dinERDDAP™pentru proiectul dumneavoastră este probabil să dureze săptămâni (şi luni pentru a prinde subtilităţi) și veți pierde capacitatea de a include modificări și soluții bug de la următoareleERDDAP™Eliberari. Noi (Evident.) cred că există multe beneficii pentru utilizareaERDDAP™cum este și de a face dumneavoastrăERDDAP™instalare accesibilă publicului. Cu toate acestea, în unele circumstanțe, s-ar putea să nu doriți să facă dvs.ERDDAP™instalare accesibilă publicului. Apoi, serviciul dvs. poate accesa și utiliza dvs. privatERDDAP™si clientii tai nu trebuie sa stie despreERDDAP™.

La jumătatea drumului​

Sau, există o altă abordare pe care s-ar putea găsi util, care este la jumătatea distanţei între căutarea înERDDAPCodul și utilizareaERDDAP™ca serviciu web independent: În clasa EDD, există o metodă statică care vă permite să faceți o instanță de un set de date (pe baza caietului de sarcinidatasets.xml) : One From Daysset Xml (Siring tDatesetID) Se întoarce o instanță a unui tabel EDD sauEDDGridSet de date. Având în vedere acest caz, puteți apela\ Face NewFileForDapQuery (Siring userDapQuery, String dir, String fileName, String file Nume tip) Astfel, aceasta este o modalitate simplă de a utilizaERDDAPmetodele de a solicita date și de a obține un fișier ca răspuns, la fel cum ar folosi un clientERDDAP™aplicație web. Dar această abordare funcționează în interiorul dumneavoastrăJavaprogram și ocolește necesitatea unui server de aplicații ca Tomcat. Folosim această abordare pentru multe dintre testele unitare ale EDDtable șiEDDGridsubclase, astfel încât să puteți vedea exemple de acest lucru în codul sursă pentru toate aceste clase.

Mediu de dezvoltare​

  • Există configuraţii pentruJettyşiDockerîn GitHub, deși este de așteptat ca lansările să aibă loc în Tomcat.

  • Opțional : ConfigurațiERDDAP™în Tomcat\ De cândERDDAP™este destinat in principal sa fie o serveta care rulează în Tomcat, vă recomandăm cu tărie să urmați standardulinstrucțiuni de instalarepentru a instala Tomcat, și apoi instalaERDDAP™în directorul lui Tomcat. Printre altele,ERDDAP™a fost proiectat pentru a fi instalat în structura directoarei Tomcat și se așteaptă ca Tomcat să furnizeze unele fișiere .jar.

  • ERDDAP™nu necesită o IDE specifică (Chris utilizează în principal codul Visual Studio, Bob a folosit EditPlus) . Noi nu folosim Eclipse, Ant, etc; nici nu oferimERDDAP- sprijin asociat pentru ei. Proiectul foloseşte Maven.

  • Folosim un fișier lot care șterge toate fișierele .class din arborele sursă pentru a ne asigura că avem o compilație curată (cu javac) .

  • În prezent folosim javac jdk-21.0.3+9 pentru a compila gov.noaa.pfeg.coastwatch.testAll (are legături cu câteva clase care nu ar fi compilate altfel) Şi fă testele. Din motive de securitate, este aproape întotdeauna cel mai bine să utilizați cele mai recente versiuni aleJava21 şi Tomcat 10.

    • Când rulăm javac sau java, directorul curent este tomcat/webapps/erddap/WEB-INF.

    • Clasa noastră Javava şi Java este Clase;../../../lib/servlet-api.jar;lib/*

    • Deci linia de comandă Javac va fi ceva de genul

    • Şi linia de comandă Java va fi ceva de genul clase/gov/noaa/pfel/coastwatch/TestAll Javapentru a imprima statistici privind colectarea gunoiului.

    • Dacă testul Toate compilaţiile, totulERDDAP™au fost elaborate nevoi. Câteva clase sunt compilate care nu sunt necesare pentruERDDAP™. Dacă compilarea TestAll reușește, dar nu compila o anumită clasă, acea clasă nu este necesară. (Există câteva clase neterminate/nefolosite.)

  • În câteva cazuri, folosim codul sursă 3rd Party în loc de fișiere .jar (în special pentruDODS) și le-au modificat ușor pentru a evita problemele de compilare cuJava21. Am făcut adesea alte mici modificări (în specialDODS) din alte motive.

  • Cele mai multe clase au metode de testare în dosarul asociat Src/test. Puteți rula testele JUnit cu testul Acest lucru va descărca mai multe fişiere zip de date pe care testele se bazează de la ultima versiune deERDDAP/erddap Test.\   NOTĂ: Maven caches descarcă, dar va deschide arhivele descărcate pe fiecare execuție, care necesită timp. Pentru a sări peste descărcarea și dezarhivarea arhivelor de date de testare, puteți specifica proprietatea "skipTestResourceDownload" către Maven (de ex. ) .

Clase importante​

Dacă doriți să se uite la codul sursă și să încerce să dau seama cumERDDAP™Merge, te rog.

  • Codul areJavaDoc comentarii, darJavaDocs nu au fost generate. Poţi să le generezi.

  • Cele mai importante clase (inclusiv cele menţionate mai jos) sunt în interiorul gov/noaa/pfel/erddap.

  • ăERDDAP™Clasa are cele mai înalte metode. Se extinde HttpServlet.

  • ERDDAP™trece cererile la cazurile de subclase deEDDGridsau tabelul EDD, care reprezintă seturi de date individuale.

  • EDStatic are cele mai multe dintre informațiile și setările statice (de exemplu, din fișierele setup.xml și mesaje.xml) și oferă servicii statice (de exemplu, trimiterea de e-mailuri) .

  • EDDGridși subclase EDDtable pars cererea, obține date de la metode specifice subclase, apoi formatați datele pentru răspuns.

  • EDDGridsubclase împinge date în GridDataAccesor (containerul de date interne pentru date în rețea) .

  • Subclasele EDD Table introduc date în subclasele TableWriter, care scriu date într-un anumit tip de fişier.

  • Alte clase (De exemplu, clase de nivel scăzut) sunt, de asemenea, importante, dar este mai puțin probabil că veți lucra pentru a le schimba.  

Contribuţii de cod​

  • Probleme GitHub Dacă doriți să contribuie, dar nu au un proiect, a se vedea lista deProbleme GitHub, multe dintre care sunt proiecte ai putea lua pe. Dacă doriţi să lucraţi la o problemă, vă rugăm să o atribuiţi dumneavoastră pentru a indica altora că lucraţi la aceasta. Problema GitHub este cel mai bun loc pentru a discuta orice întrebări pentru a continua cu munca pe această temă.

  • Dacă schimbarea pe care doriți să o faceți este una dintre cazurile comune de mai jos, vă rugăm să creați oProblema GitHubindicând schimbarea pe care intenţionaţi să o faceţi. Apoi, odată ce schimbarea este completă, face o cerere de tragere pentru a solicita unirea. Modificările comune includ:

    • Vrei să scrii o altă subclasă deEDDGridsau tabelul EDD pentru a gestiona un alt tip de sursă de date. Dacă da, vă recomandăm să găsiți cea mai apropiată subclasă existentă și să utilizați acest cod ca punct de plecare.

    • Doriți să scrieți o altă metodă SaveAs_FileType_. Dacă da, vă recomandăm să găsiți cea mai apropiată metodă de salvare existentăAs_FileType_ înEDDGridfie tabelul EDD și utilizați codul ca punct de plecare.

Aceste situații au avantajul că codul pe care îl scrieți este autonom. Nu va trebui să ştii toate detaliileERDDAPE ceva intern. Și va fi ușor pentru noi să încorporăm codul înERDDAP. Rețineți că, dacă depuneți codul, licența va avea nevoie de compatibil cuERDDAP™ licență (de exemplu,Apache,BSD, sauMIT-X) . Vom lista contribuția încredite.

  • Dacă aveți o caracteristică care nu este acoperită mai sus, la care ați dori să adăugațiERDDAP, este recomandat să se creeze mai întâi un fir de discuție înDiscuţii GitHub. Pentru caracteristici/modificări semnificative, consiliul tehnic le va discuta și va decide dacă să aprobe adăugarea acestuia laERDDAP™.

Judecând contribuțiile de cod​

Dacă doriți să prezentați codul sau alte modificări care trebuie incluse înERDDAPE grozav. Contribuția dumneavoastră trebuie să îndeplinească anumite criterii pentru a fi acceptată. Dacă urmaţi instrucţiunile de mai jos, creşteţi considerabil şansele ca contribuţia dumneavoastră să fie acceptată.  

  • ăERDDAP™Proiectul este gestionat de NATD (NOAADirector tehnic desemnat) cu informații de la un consiliu tehnic. Din 2007 (începutulERDDAP) prin 2022, acela era Bob Simons. (De asemenea, fondatorul-lider) . Începând din ianuarie 2023, acesta este Chris John. Practic, NATD este responsabil pentruERDDAP, deci s / el are cuvântul final despre deciziiERDDAP™codul, în special în ceea ce privește proiectul și dacă o anumită cerere de retragere va fi acceptată sau nu. Acesta trebuie să fie în acest fel parțial din motive de eficiență (functioneaza foarte bine pentru Linus Torvalds si Linux) și parțial din motive de securitate: Cineva trebuie să spună oamenilor de la securitatea IT că îşi asumă responsabilitatea pentru securitatea şi integritatea codului.  

  • NATD nu garantează că va accepta codul tău. Dacă un proiect pur și simplu nu funcționează la fel de bine ca am sperat și dacă nu poate fi salvat, NATD nu va include proiectul înERDDAP™distribuţie. Te rog să nu te simţi prost. Uneori proiectele nu funcţionează la fel de bine cum speram. Se întâmplă tuturor dezvoltatorilor de software. Dacă urmaţi instrucţiunile de mai jos, creşteţi mult şansele de succes.  

  • Este mai bine dacă schimbările sunt de interes general și utilitate. Dacă codul este specific organizației dumneavoastră, este, probabil, cel mai bine pentru a menține o ramură separată deERDDAP™pentru uzul dumneavoastră. Axiom face asta. Din fericire, Git face acest lucru ușor de făcut. NATD vrea să mențină o viziune consecventă pentruERDDAP, nu permite să devină un proiect chiuveta bucătărie în cazul în care toată lumea adaugă o caracteristică personalizată pentru proiectul lor.  

  • UrmeazăJavaConvenţii de Cod. În general, codul dumneavoastră ar trebui să fie de bună calitate și ar trebui să urmeze originalulJavaConvenții de cod: pune fișiere .class în locul potrivit în structura director, da .class fișiere un nume adecvat, include adecvatJavaComentarii Doc, includ //comentarii la începutul fiecărui punct de cod, liniuță cu 4 spații (nu tab) , evita liniile >80 caractere, etc. Convențiile se schimbă și codul sursă nu este întotdeauna complet actualizat. Atunci când există îndoieli, se potrivește cu codul convențiilor și nu există codul existent.

  • Utilizați clase descriptive, metode și nume variabile. Asta face codul mai uşor de citit pentru alţii.  

  • Evitați codul fantezie. Pe termen lung, tu sau alte persoane va trebui să dau seama codul pentru a-l menține. Deci, vă rugăm să utilizați metode simple de codificare care sunt astfel mai ușor pentru alții (inclusiv tu în viitor) să-mi dau seama. Evident, dacă există un avantaj real de a folosi unele fantezieJavacaracteristică de programare, utilizați-l, dar documentați pe scară largă ceea ce ai făcut, de ce, și cum funcționează.  

  • Lucrează cu Consiliul Tehnic înainte de a începe. Dacă sperați să obțineți modificările de cod tras înERDDAP™, Consiliul Tehnic va dori cu siguranta sa vorbeasca despre ceea ce ai de gand sa faci si cum o vei face inainte de a face orice modificari ale codului. În acest fel, putem evita să faci schimbări pe care NATD, în cele din urmă, nu le acceptă. Atunci când faci munca, NATD și Comitetul tehnic este dispus să răspundă la întrebări pentru a vă ajuta să dau seama codul existent și (global) cum să abordezi proiectul.  

  • Lucrează independent (cât mai mult posibil.) după ce începi. Spre deosebire de "Lucrarea cu Consiliul Tehnic" de mai sus, după ce ați început proiectul, NATD vă încurajează să lucrați cât mai independent posibil. Dacă NATD trebuie să-ţi spună aproape totul şi să răspundă la multe întrebări (mai ales cele la care ai fi putut răspunde citind documentația sau codul) , atunci eforturile tale nu sunt o economie de timp pentru NATD și s / el ar putea face la fel de bine munca ei înșiși. EsteLuna om miticproblemă. Desigur, ar trebui să comunicăm. Ar fi minunat să vedem periodic activitatea dumneavoastră în curs pentru a vă asigura că proiectul este pe drumul cel bun. Dar cu cât poţi lucra mai mult independent (după ce comitetul tehnic este de acord cu privire la sarcina în cauză și abordarea generală) Cu cât mai bine.  

  • Evitaţi insectele. În cazul în care un bug nu este prins înainte de o eliberare, provoacă probleme pentru utilizatori (cel mult) , returnează informațiile greșite (cel mai rău) , este o pata peERDDAPreputatia lui, si va persista pe out-of-dateERDDAP™instalații de ani de zile. Munca foarte greu pentru a evita bug-uri. O parte din acest lucru este scris cod curat (deci este mai uşor să vezi probleme) . O parte din aceasta este scris teste unitate. O parte din aceasta este o atitudine constantă de evitare a insectelor atunci când scrie cod. Nu face NATD regret adăugarea codului laERDDAP™.  

  • Scrie un test sau teste unitate. Pentru un nou cod, ar trebui să scrieți testele JUnit într-un fișier de testare. Vă rugăm să scrieți cel puțin o metodă individuală de testare care testează în detaliu codul pe care îl scrieți și îl adăugați la fișierul de testare JUnit al clasei, astfel încât acesta să fie rulat automat. Unitate (și legate) Testele sunt una dintre cele mai bune modalități de a prinde bug-uri, inițial, și pe termen lung (ca alte lucruri schimba inERDDAP™) . Aşa cum a spus Bob, "Anchetele de Unităţi mă lasă să dorm noaptea."  

  • Fă-l ușor pentru NATD să înțeleagă și să accepte modificările în cererea dumneavoastră de tragere. O parte din aceasta este scrierea unei metode de încercare unitare (s) . O parte din aceasta este limitarea modificărilor la o secțiune de cod (sau o singură clasă) dacă este posibil. NATD nu va accepta nici o cerere de tragere cu sute de modificări în tot codul. NATD spune oamenilor de securitate IT că şi-a asumat responsabilitatea pentru securitatea şi integritatea codului. Dacă există prea multe schimbări sau sunt prea greu de dat seama, atunci este prea greu pentru a verifica modificările sunt corecte și nu introduce bug-uri sau probleme de securitate.  

  • Să fie simplu. O temă de ansamblu bună pentru codul tău este: Păstrați-l simplu. Codul simplu este ușor pentru alții (inclusiv tu în viitor) să citească şi să menţină. E uşor pentru NATD să înţeleagă şi să accepte.  

  • Preia responsabilitatea pe termen lung pentru codul tău. Pe termen lung, este cel mai bine dacă vă asumaţi responsabilitatea permanentă pentru menţinerea codului şi răspunsul la întrebări despre aceasta (de exemplu, înERDDAP™Google Group) . După cum observă unii autori, codul este o datorie, precum și un activ. Dacă un bug este descoperit în viitor, este mai bine dacă-l repara pentru că nimeni nu știe codul mai bine decât tine (de asemenea, astfel încât există un stimulent pentru a evita bug-uri, în primul rând) . NATD nu cere un angajament ferm de a asigura întreținerea în curs. NATD spune doar că efectuarea întreținerii va fi foarte apreciat.