Пропустить основной контент

Руководство программиста

Это то, с чем должен работать только программист.ERDDAP?JavaКлассы должны знать.

Получение исходного кода​

 

  • Источник кода на GitHub Исходный код для последних общедоступных версий и версий в разработке также доступен черезGitHub. Пожалуйста, прочтитеВикиДля этого проекта. Если вы хотите изменить исходный код (и возможно внесение изменений в стандартERDDAP™распределение) Это рекомендуемый подход.

ERDDAP™зависимости​

ERDDAP™использует Maven для загрузки зависимостей кода, а также некоторых статических справочных файлов (WEB-INF/ref) . Это делается для того, чтобы избежать хранения большого количества файлов в хранилище. Вы можете использовать «mvn-компиляцию», которая будет использовать зависимости и файлы ref. Вы также можете использовать пакет mvn для создания военного файла. Вы можете вручную загрузить файлы ref:

  • etopo1\ice\g\i2.zipОтключите его в /WEB-INF/ref/.

  • Ref_files.zipОтключите его в /WEB-INF/ref/.

  • erddapContent.zip (версия 1.0.0, 20333 байт, MD5=2B8D2A5AE5ED73E3A42B529C168C60B5, датированная 2024-10-14) и распаковывать его в tomcat, создавая_tomcat_/content/erddap.

ПРИМЕЧАНИЕ: По умолчанию Maven будет кэшировать статические ссылки и тестировать архивы данных и извлекать их только при загрузке новой версии. Чтобы полностью пропустить загрузку, вы можете установить свойства «skipResourceDownload» и / или «skipTestResourceDownload» в Maven. (Например, 'mvn -DskipResourceDownload package пункт) . Для принудительной экстракции установите «-Ddownload.unpack=true» и «-Ddownload.unpackWhenChanged=false».

  • ERDDAP™и его субкомпоненты имеют очень либеральный, открытый исходный кодлицензииТаким образом, вы можете использовать и изменять исходный код для любых целей, для получения прибыли или не для получения прибыли. Обратите внимание, чтоERDDAP™Многие субкомпоненты имеют лицензии, требующие подтверждения источника кода, который вы используете. Видишь?Кредиты. Независимо от того, требуется это или нет, это просто хорошая форма, чтобы признать всех этих участников.

  • Используйте код для других проектов

Хотя вы можете использовать частиERDDAP™Код для других проектов предупреждают, что код может и будет меняться. Мы не обещаем поддерживать другие виды использования нашего кода. Git и GitHub станут вашими основными решениями для решения этой проблемы — Git позволяет вам объединять наши изменения в ваши изменения. Для многих ситуаций, когда у вас может возникнуть соблазн использовать некоторыеERDDAP™В вашем проекте, мы думаем, вы найдете его намного проще установить и использовать.ERDDAP™Как есть, Затем напишите другие сервисы, которые используютERDDAPУслуги. Вы можете создать свой собственныйERDDAP™Установка грубо через час или два. Вы можете создать свой собственныйERDDAP™Установка в полированной форме за несколько дней (В зависимости от количества и сложности ваших наборов данных) . Но взламывать частиERDDAP™Для вашего проекта, вероятно, потребуются недели. (Месяцы, чтобы уловить тонкости) и вы потеряете возможность вносить изменения и исправления ошибок из последующихERDDAP™освобождения. Мы (очевидно) Есть много преимуществ использованияERDDAP™Как сделать и сделать свойERDDAP™Установка общедоступна. Однако в некоторых случаях вы можете не захотеть делать своиERDDAP™Установка общедоступна. Затем ваша служба может получить доступ и использовать вашу частнуюERDDAP™Ваши клиенты не должны знать оERDDAP™.

На полпути​

Или есть другой подход, который вы можете найти полезным, который находится на полпути между погружением вERDDAPКод и использованиеERDDAP™Как самостоятельный веб-сервис: В классе EDD есть статический метод, который позволяет сделать экземпляр набора данных. (Исходя из спецификации вdatasets.xml) : один из набора данных Xml (Струнный tDatasetID) Он возвращает экземпляр EDDTable илиEDDGridнабор данных. В этом случае вы можете позвонить 'сделатьNewFileForDapQuery (String userDapQuery, String dir, String fileName, String file Имя типа) сообщить экземпляру о создании файла данных определенного типа файла с результатами пользовательского запроса. Это простой способ использованияERDDAPметоды запроса данных и получения файла в ответ, так же, как клиент будет использоватьERDDAP™веб-приложение. Но этот подход работает внутри вас.JavaЭто позволяет обойти потребность в сервере приложений, таком как Tomcat. Мы используем этот подход для многих единичных тестов EDDTable.EDDGridПодклассы, так что вы можете увидеть примеры этого в исходном коде для всех этих классов.

Окружающая среда​

  • Существуют конфигурации дляДжеттииДокерВ GitHub релизы, как ожидается, будут запущены в Tomcat.

  • необязательный : НастройкаERDDAP™В Tomcat С тех порERDDAP™В основном предназначен для сервлетов, работающих в Tomcat, мы настоятельно рекомендуем вам следовать стандарту.Инструкция по установкеустановить Tomcat, а затем установитьERDDAP™в каталоге веб-приложений Tomcat. Среди прочего,ERDDAP™Он был разработан для установки в структуру каталогов Tomcat и ожидает, что Tomcat предоставит некоторые файлы .jar.

  • ERDDAP™Не требует специальной IDE (Крис в основном использует Visual Studio Code, Боб — EditPlus) . Мы не используем Eclipse, Ant и т. Д.; Мы не предлагаемERDDAPсвязанной с ними поддержкой. Проект использует Maven.

  • Мы используем пакетный файл, который удаляет все файлы .class в исходном дереве, чтобы обеспечить чистую компиляцию. (с Javac) .

  • В настоящее время Adoptium использует javac jdk-21.0.3+9 для компиляции gov.noaa.pfeg.coastwatch.TestAll (Он имеет ссылки на несколько классов, которые не были бы собраны иначе.) и провести тесты. Из соображений безопасности почти всегда лучше использовать последние версии.Java21 и Tomcat 10.

    • Когда мы запускаем javac или java, текущим каталогом является tomcat/webapps/erddap/WEB-INF.

    • Наш курс джавака и джавы "классы;../../../lib/servlet-api.jar;lib/*"

    • Таким образом, ваша командная строка будет чем-то вроде "javac -кодирование классов UTF-8 -cp;../../../lib/servlet-api.jar;lib/* классы/gov/noaa/pfel/coastwatch/TestAll.java"

    • И ваша командная строка Java будет чем-то вроде 'java -cp classs;../../../lib/servlet-api.jar;lib/* -Xmx4000M -Xms4000M Классы/gov/noaa/pfel/coastwatch/TestAll "Необязательно: вы можете добавить "-verbose:gc", который говорит:JavaРаспечатать статистику сбора мусора.

    • Если тест Все составы, всеERDDAP™Потребности были собраны. Составлены несколько классов, которые не нужны дляERDDAP™. Если компиляция TestAll успешна, но не компилирует какой-то класс, этот класс не нужен. (Есть незавершенные/неиспользованные классы.)

  • В некоторых случаях мы используем исходный код 3-й стороны вместо файлов .jar. (Особенно дляDODS) и слегка изменили их, чтобы избежать проблем, связанных сJava21. Мы часто вносили другие незначительные изменения (В частности,DODS) по другим причинам.

  • Большинство классов имеют методы тестирования в связанных с ними файлах src/test. Вы можете запустить тесты JUnit с помощью команды «mvn test». Это позволит загрузить несколько zip-файлов данных, на которые опираются тесты из последнего выпуска.ERDDAP/erddap Тест.   ПРИМЕЧАНИЕ: Maven кэширует загрузки, но разблокирует загруженные архивы при каждом выполнении, что требует времени. Чтобы пропустить загрузку и распаковывая архивы тестовых данных, вы можете указать свойство «skipTestResourceDownload» для Maven (Например, 'mvn -DskipTestResourceDownload package пункт) .

Важные классы​

Если вы хотите посмотреть на исходный код и попытаться выяснить, какERDDAP™Работайте, пожалуйста.

  • Код имеетJavaКомментарий Док, ноJavaДокументы не были созданы. Не стесняйтесь генерировать их.

  • Самые важные классы (включая упомянутые ниже) Они находятся в пределах gov/noaa/pfel/erddap.

  • TheERDDAP™Класс имеет методы высочайшего уровня. Расширяется HttpServlet.

  • ERDDAP™передает запросы экземплярам подклассовEDDGridили EDDTable, которые представляют собой отдельные наборы данных.

  • EDStatic имеет большую часть статической информации и настроек. (Например, из файлов setup.xml и message.xml) Предлагает статические услуги (например, отправка электронных писем) .

  • EDDGridПодклассы EDDTable анализируют запрос, получают данные из методов подкласса, затем форматируют данные для ответа.

  • EDDGridПодклассы переносят данные в GridDataAccessor (Внутренний контейнер данных для сетчатых данных) .

  • Подклассы EDDTable перемещают данные в подклассы TableWriter, которые записывают данные в определенный тип файла на лету.

  • Другие классы (Например, классы низкого уровня) Это также важно, но менее вероятно, что вы будете работать, чтобы изменить их.  

Код вкладов​

  • Проблемы GitHub Если вы хотите внести свой вклад, но у вас нет проекта, посмотрите списокПроблемы GitHubМногие из этих проектов вы можете взять на себя. Если вы хотите работать над вопросом, пожалуйста, назначьте его себе, чтобы указать другим, что вы работаете над ним. Вопрос GitHub — лучшее место для обсуждения любых вопросов о том, как продолжить работу над этим вопросом.

  • Если изменение, которое вы хотите внести, является одним из приведенных ниже распространенных случаев, пожалуйста, создайтеПроблема GitHubУкажите изменения, которые вы намерены внести. Затем, как только изменение будет завершено, сделайте запрос на слияние. Общие изменения включают:

    • Вы хотите написать еще один подклассEDDGridили EDDTable для обработки другого типа источника данных. Если это так, мы рекомендуем вам найти ближайший существующий подкласс и использовать этот код в качестве отправной точки.

    • Вы хотите написать другой метод SaveAs_FileType_. Если это так, мы рекомендуем вам найти ближайший существующий метод SaveAs_FileType_.EDDGridИспользуйте этот код в качестве отправной точки.

Эти ситуации имеют то преимущество, что код, который вы пишете, является автономным. Вам не нужно будет знать все деталиERDDAPВнутренности. И нам будет легко включить ваш код вERDDAP. Обратите внимание, что если вы отправляете код, лицензия должна быть совместима сERDDAP™ лицензия (например,Апач,BSDилиMIT-X) . Мы перечислим ваш вклад вкредиты.

  • Если у вас есть функция, не описанная выше, которую вы хотели бы добавить кERDDAP, рекомендуется сначала создать дискуссионную нить вОбсуждение GitHub. В случае значительных изменений Технический совет обсудит их и примет решение о том, следует ли одобрить их добавление.ERDDAP™.

Оцените свой вклад в код​

Если вы хотите представить код или другие изменения, которые будут включены вERDDAPЭто здорово. Ваш вклад должен соответствовать определенным критериям, чтобы быть принятым. Если вы будете следовать приведенным ниже рекомендациям, вы значительно увеличите шансы на принятие вашего вклада.  

  • TheERDDAP™Проектом управляет NATD (NOAAНазначен технический директор) При участии технического совета. С 2007 года (В началеERDDAP) До 2022 года это был Боб Саймонс. (Также основатель-лидер) . Начиная с января 2023 года, это Крис Джон. Таким образом, NATD несет ответственность заERDDAPУ него есть последнее слово в принятии решений оERDDAP™код, в частности, о дизайне и о том, будет ли принят данный запрос на вытягивание или нет. Это должно быть частично из-за эффективности. (Он отлично работает для Линуса Торвальдса и Linux.) Частично по соображениям безопасности: Кто-то должен сказать сотрудникам ИТ-безопасности, что он несет ответственность за безопасность и целостность кода.  

  • NATD не гарантирует, что он примет ваш код. Если проект просто не работает так хорошо, как мы надеялись, и если он не может быть спасен, NATD не будет включать проект в проект.ERDDAP™распределения. Пожалуйста, не расстраивайтесь. Иногда проекты не работают так хорошо, как хотелось бы. Это происходит со всеми разработчиками программного обеспечения. Если вы будете следовать приведенным ниже рекомендациям, вы значительно увеличите свои шансы на успех.  

  • Лучше всего, если изменения представляют общий интерес и полезны. Если код специфичен для вашей организации, вероятно, лучше всего поддерживать отдельную ветвь.ERDDAP™для вашего использования. Аксиома делает это. К счастью, Git делает это легко. NATD хочет поддерживать последовательное видение будущего.ERDDAPНе позволяйте ему стать проектом кухонной раковины, где каждый добавляет специальную функцию для своего проекта.  

  • Следуй за мной.JavaКодовые конвенции. В целом, ваш код должен быть хорошего качества и должен соответствовать оригиналу.JavaКодовые конвенцииПоместите файлы .class в нужное место в структуре каталога, дайте файлам .class соответствующее имя, включите правильноеJavaКомментарии Doc, включают //комментарии в начале каждого абзаца кода, отступ с 4 пробелами (не закладка) Избегайте строк >80 символов и т.д. Соглашения меняются, и исходный код не всегда полностью обновлен. Если есть сомнения, сопоставьте код с существующими соглашениями, а не с существующими.

  • Используйте описательный класс, метод и переменные имена. Это облегчает чтение кода для других.  

  • Избегайте модного кода. В долгосрочной перспективе вам или другим людям придется выяснить код, чтобы сохранить его. Поэтому, пожалуйста, используйте простые методы кодирования, которые таким образом легче для других. (включая вас в будущем) Чтобы понять. Очевидно, если есть реальное преимущество в использовании какой-то фантазии.JavaФункция программирования, используйте ее, но подробно документируйте, что вы сделали, почему и как это работает.  

  • Работайте с техническим советом, прежде чем начать. Если вы хотите, чтобы ваши изменения кода были втянуты вERDDAP™Технический совет определенно захочет поговорить о том, что вы собираетесь делать и как вы собираетесь это делать, прежде чем вносить какие-либо изменения в код. Таким образом, мы можем избежать изменений, которые NATD, в конце концов, не принимает. Когда вы выполняете работу, NATD и технический совет готовы ответить на вопросы, чтобы помочь вам выяснить существующий код. (общий) Как реализовать свой проект.  

  • Работать самостоятельно (как можно больше) После того, как ты начнешь. В отличие от вышеупомянутого «Работа с техническим советом», после того, как вы приступите к работе над проектом, NATD рекомендует вам работать как можно более независимо. Если NATD должен рассказать вам почти все и ответить на множество вопросов (Особенно те, на которые вы могли бы ответить, прочитав документацию или код.) Тогда ваши усилия не экономят время для NATD, и он может также сделать работу самостоятельно. ЭтоМифический месяц человекаПроблема. Конечно, мы должны продолжать общаться. Было бы здорово периодически видеть вашу работу, чтобы убедиться, что проект находится на пути. Чем больше вы можете работать самостоятельно (после согласования Технической комиссией поставленной задачи и общего подхода) Чем лучше.  

  • Избегайте жуков. Если ошибка не обнаружена до релиза, это создает проблемы для пользователей. (В лучшем) возвращает неверную информацию (В худшем случае) Это пятно наERDDAPРепутация и будет оставаться устаревшейERDDAP™установки в течение многих лет. Работайте очень усердно, чтобы избежать ошибок. Часть этого написания чистого кода (Так легче увидеть проблемы.) . Частью этого является написание единичных тестов. Частью этого является постоянное избегание ошибок при написании кода. Не заставляйте NATD сожалеть о добавлении вашего кодаERDDAP™.  

  • Напишите единичный тест или тесты. Для нового кода вы должны написать тесты JUnit в тестовом файле. Пожалуйста, напишите хотя бы один индивидуальный метод тестирования, который тщательно проверяет написанный вами код и добавляет его в тестовый файл класса JUnit, чтобы он запускался автоматически. Подразделение (связанный) Тесты являются одним из лучших способов поймать баги, как в начале, так и в долгосрочной перспективе. (Как другие вещи меняются вERDDAP™) . Как сказал Боб: «Единые тесты — это то, что позволяет мне спать по ночам».  

  • Упростите NATD понимание и принятие изменений в вашем запросе на вытягивание. Частью этого является написание метода модульного тестирования. (s) . Часть этого ограничивает ваши изменения в одном разделе кода. (или один класс) Если возможно. NATD не будет принимать запросы с сотнями изменений по всему коду. NATD сообщает ИТ-безопасности, что он / она берет на себя ответственность за безопасность и целостность кода. Если изменений слишком много или их слишком трудно выяснить, то просто слишком сложно проверить, что изменения верны и не вводить ошибки или проблемы безопасности.  

  • Держите его простым. Хорошая общая тема для вашего кода: Держите его простым. Простой код прост для других (включая вас в будущем) Читать и поддерживать. Для NATD легко понять и таким образом принять.  

  • Возьмите на себя долгосрочную ответственность за свой код. В долгосрочной перспективе лучше всего, если вы берете на себя постоянную ответственность за поддержание своего кода и ответы на вопросы об этом. (Например, вERDDAP™Google Group) . Как отмечают некоторые авторы, код является обязательством, а также активом. Если ошибка обнаружена в будущем, лучше всего исправить ее, потому что никто не знает ваш код лучше вас. (Кроме того, есть стимул, чтобы избежать ошибок в первую очередь.) . NATD не требует твердого обязательства по обеспечению постоянного технического обслуживания. NATD просто говорит, что выполнение технического обслуживания будет высоко оценено.