Developer SDK » Java » [:На редактировании:] Мой перевод документации к Tomcat 7

[:На редактировании:] Мой перевод документации к Tomcat 7

Автор: | | ,

Ниже представлен мой НЕПРОФЕССИОНАЛЬНЫЙ перевод одной из глав документации к Tomcat. Перевод делается для себя, однако если кому то он окажется полезен, то буду только рад и признателен комментариям. Источник: http://localhost:8080/docs/appdev/source.html (надеюсь что вы поймете иронию ссылки)

Перевод осуществлялся с помощью переводчиков google, yandex, и словарей ABBY Lingvo, yandex

При переводе максимально старался придерживаться здравого смысла и логики, но не всегда это получалось, поэтому повторюсь: Объективные комментарии только приветствуются.

Оригинал Перевод

Source Organization

Организация исходников

Directory Structure

Структура каталогов
The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat. Описание, представленное ниже использует переменную $CATALINA_BASE для разрешения базового каталога на основе относительных путей. Если Вы не сконфигурировали Tomcat для нескольких  экземпляров каталогов (для использования другого каталога домашней директории проектов)  установив CATALINA_BASE каталог, тогда значение $CATALINA_BASE будет установлена по значению $CATALINA_HOME каталога, куда был установлен Tomcat.
A key recommendation of this manual is to separate the directory hierarchy containing your source code (described in this section) from the directory hierarchy containing your deployable application (described in the preceding section). Maintaining this separation has the following advantages: Ключевой рекомендацией настоящего руководства является разделение иерархии каталогов Вашего исходного кода (описанного в этом разделе) от каталогов разворачиваемого приложения (описанных в предыдущем разделе). Придерживаясь этого разделения можно получить следующие преимущества: [прим: т.е. исходники и бинарники хранятся отдельно]
  • The contents of the source directories can be more easily administered, moved, and backed up if the «executable» version of the application is not intermixed.
  • Source code control is easier to manage on directories that contain only source files.
  • The files that make up an installable distribution of your application are much easier to select when the deployment hierarchy is separate.
  • Содержимое каталогов исходного когда можно на много легче администрировать, перемещать, и архивировать «исполняемые» версии, если приложение не смешано.
  • Исходный код более легок для управления в каталогах, содержащих только файлы исходников
  • Файлы, которые являются установочными вашего распределенного приложения, гораздо легче выбрать если иерархия разделена
As we will see, the ant development tool makes the creation and processing of such directory hierarchies nearly painless. Как мы увидим, инструмент разработки ant создает и обрабатывает такие директории почти безболезненно.
The actual directory and file hierarchy used to contain the source code of an application can be pretty much anything you like. However, the following organization has proven to be quite generally applicable, and is expected by the example build.xml configuration file that is discussed below. All of these components exist under a top level project source directory for your application:  Фактически, каталоги и иерархия файлов используемая для исходного кода приложения могут быть какими угодно. Однако следующая организация весьма распространенной и она используется в качестве примера в конфигурационном файле build.xml который  обсуждается ниже. Все эти компоненты находятся в каталоге верхнего уровня Вашего проекта.
  • docs/ — Documentation for your application, in whatever format your development team is using.
  •  docs/ — Документация приложения, В любом формате используемом вашей командой.
  • src/ — Java source files that generate the servlets, beans, and other Java classes that are unique to your application. If your source code is organized in packages (highly recommended), the package hierarchy should be reflected as a directory structure underneath this directory.
  •  src/ — Исходные файлы Java генерирующие сервлеты, bean-компоненты и другия Java классы приложения. Если сходный код организован в в пакеты (настоятельно рекомендуется), организация иерархии пакетов должна быть отражена под этим каталогом.
  • web/ — The static content of your web site (HTML pages, JSP pages, JavaScript files, CSS stylesheet files, and images) that will be accessible to application clients. This directory will be the document root of your web application, and any subdirectory structure found here will be reflected in the request URIs required to access those files.
  •  web/ — Статическое содержимое вашего web сайта (HTML страницы, JSP страницы, JavaScript файлы, каскадные таблицы стилей CSS, и изображения) которые будут доступны для клиентов приложения. этот каталог будет корневым каталогом для приложения и любой подкаталог расположенный здесь будет отражен в URI запросе доступа к файлу.
  • web/WEB-INF/ — The special configuration files required for your application, including the web application deployment descriptor (web.xml, defined in the Servlet Specification), tag library descriptors for custom tag libraries you have created, and other resource files you wish to include within your web application. Even though this directory appears to be a subdirectory of your document root, the Servlet Specification prohibits serving the contents of this directory (or any file it contains) directly to a client request. Therefore, this is a good place to store configuration information that is sensitive (such as database connection usernames and passwords), but is required for your application to operate successfully.
  •  web/WEB-INF/ — Специальные файлы конфигурации, необходимые для приложения, в том числе, дискриптор развертывания приложения (web.xml, определеный в Спецификации сервлетов), дескрипторы библиотеки тегов для созданных вами пользовательских библиотек тегов, и других файлов ресурсов, включаемых в приложение. И хотя этот каталог находится в подкаталоге корня документов, спецификация сервлетов запрещает передачу содержимого этого каталога (или любых файлов в нем содержащихся) непосредственно на запрос клиета. Поэтому это отличное место для хранения секретной конфигурационной информации (такой как регистрационные данные для подключения к базе данных), но необходимой для работы вашего web приложения
During the development process, two additional directories will be created on a temporary basis:  Во время разработки используется две дополнительные временные директории.
  • build/ — When you execute a default build (ant), this directory will contain an exact image of the files in the web application archive for this application. Tomcat allows you to deploy an application in an unpacked directory like this, either by copying it to the $CATALINA_BASE/webapps directory, or byinstalling it via the «Manager» web application. The latter approach is very useful during development, and will be illustrated below.
  •  build/ — Если вы используете утилиту сборки по умолчанию (ant), этот каталог будет содержать точные копии образов фалов web приложения. Tomcat позволяет развернуть web приложения путем копирования их в каталог $CATALINA_BASE/webapps, или установив его через веб утилиту Manager. Последний подход очень полезен во время разработки и будет проиллюстрирован далее.
  • dist/ — When you execute the ant dist target, this directory will be created. It will create an exact image of the binary distribution for your web application, including an license information, documentation, and README files that you have prepared.
  •  dist/ — Этот каталог будет создан тогда, когда будет запущен ant dist. Это позволит создать точный образ дистрибутива вашего web приложения, включая подготовленные Вами лицензионную информацию, документацию и README файл,
Note that these two directories should NOT be archived in your source code control system, because they are deleted and recreated (from scratch) as needed during development. For that reason, you should not edit any source files in these directories if you want to maintain a permanent record of the changes, because the changes will be lost the next time that a build is performed.  Обратите внимание, что эти две директории НЕ должны быть включены в Вашу систему исходного кода, потому что они удаляются и создаются заново (с нуля) по мере необходимости в процессе разработки. Поэтому Вы не должны редактировать любые исходные файлы в этих каталогах ?если вы хотите поддерживать постоянную запись изменений, потому что изменения будут потерянны при запуске следующей сборки.

External Dependencies

Внешние зависимости
What do you do if your application requires JAR files (or other resources) from external projects or packages? A common example is that you need to include a JDBC driver in your web application, in order to operate.  Что делать, если web приложению необходимы JAR файлы (или другие ресурсы) из внешних проектов? Наиболее общий пример — необходимость включения для использования JDBC драйвера в ваше web приложение
Different developers take different approaches to this problem. Some will encourage checking a copy of the JAR files you depend on into the source code control archives for every application that requires those JAR files. However, this can cause significant management issues when you use the same JAR in many applications — particular when faced with a need to upgrade to a different version of that JAR file.  Различные разработчики используют различные подходы для решений этой проблемы. Некоторые поощряют размещения копий необходимых JAR файлов в архивы каждого приложения, которые в них нуждаются. Однако, это может вызвать значительные проблемы управления когда вы используете несколько JAR файлов в различных приложениях, в частности когда возникает необходимость в обновлении нескольких JAR файлов.
Therefore, this manual recommends that you NOT store a copy of the packages you depend on inside the source control archives of your applications. Instead, the external dependencies should be integrated as part of the process of building your application. In that way, you can always pick up the appropriate version of the JAR files from wherever your development system administrator has installed them, without having to worry about updating your application every time the version of the dependent JAR file is changed.  Поэтому это руководство рекомендует НЕ хранить копии пакетов в архиве вашего приложения. Вместо этого внешние зависимости могут быть интегрированы во время процесса сборки вашего приложения. В этом случае Вы всегда сможете подобрать соответствующие версии JAR файлов из установленного системным администратором хранилища, не беспокоясь о обновлении вашего приложения каждый раз когда версия зависимого файла обновлена.
In the example Ant build.xml file, we will demonstrate how to define build properties that let you configure the locations of the files to be copied, without having to modify build.xml when these files change. The build properties used by a particular developer can be customized on a per-application basis, or defaulted to «standard» build properties stored in the developer’s home directory.  В примере файла Ant build.xml мы продемонстрируем как определить параметры сборки которые позволят Вам  настроить пути файлов для копирования без необходимости модификации файла build.xml когда эти файлы изменены. Свойства сборки используемые конкретным разработчиком могут быть определены для каждого приложения отдельно, или определены «стандартные» параметры сборки хранящиеся в домашней директории разработчика
In many cases, your development system administrator will have already installed the required JAR files into the lib directory of Tomcat. If this has been done, you need to take no actions at all — the example build.xml file automatically constructs a compile classpath that includes these files.  В большенстве случаев, Вашим администратором системы разработки будут уже установленны требуемые JAR файлы в каталог lib системы Tomcat. Если это сделано, вам не нужно предпринимать накаких действий. Файл примера build.xml автоматический построит classpaht с включеннием этих файлов.

Source Code Control

Контроль исходного кода
As mentioned earlier, it is highly recommended that you place all of the source files that comprise your application under the management of a source code control system like the Concurrent Version System (CVS). If you elect to do this, every directory and file in the source hierarchy should be registered and saved — but none of the generated files. If you register binary format files (such as images or JAR libraries), be sure to indicate this to your source code control system. Как упоминалось выше, эта важная рекомендация для размещения всех исходных файлов которые содержит Ваше приложение в соответствии с системой управления исходным кодом такой как Concurrent Version System (Система параллельных версий) (CVS). Если вы сделали это, каждый каталог и файл в иерархии исходного кода должны быть зарегистрированы и сохранены — но не должно быть автоматически генерируемых файлов. Если Вы регистрируете двоичные файлы (такие как JAR файлы или изображения) не забудьте включить их в систему контроля исходного кода
We recommended (in the previous section) that you should not store the contents of the build/ and dist/ directories created by your development process in the source code control system. An easy way to tell CVS to ignore these directories is to create a file named .cvsignore (note the leading period) in your top-level source directory, with the following contents:

build
dist
build.properties

The reason for mentioning build.properties here will be explained in the Processes section.

  В  предыдущей секции мы рекомендовали не хранить содержимое каталогов build/ и dist/, создаваемых в процессе сборки в системе контроля исходного кода. Легкий способ сообщить CVS игнорировать эти каталоги — создать файл с именем .cvsignore (?????????) в вашем каталоге верхнего уровня с следующим содержимым:

build
dist
build.properties

Причина упоминания здесь build.properties будет описана в разделе Процессы
Detailed instructions for your source code control environment are beyond the scope of this manual. However, the following steps are followed when using a command-line CVS client:  Подробная инструкция по среде управления исходным кодом выходит за рамки данного руководства. Однако следующие действия выполняются при использовании командной строки CVS клиента
  • To refresh the state of your source code to that stored in the the source repository, go to your project source directory, and execute cvs update -dP.
  • When you create a new subdirectory in the source code hierarchy, register it in CVS with a command like cvs add {subdirname}.
  • When you first create a new source code file, navigate to the directory that contains it, and register the new file with a command like cvs add {filename}.
  • If you no longer need a particular source code file, navigate to the containing directory and remove the file. Then, deregister it in CVS with a command likecvs remove {filename}.
  • While you are creating, modifying, and deleting source files, changes are not yet reflected in the server repository. To save your changes in their current state, go to the project source directory and execute cvs commit. You will be asked to write a brief description of the changes you have just completed, which will be stored with the new version of any updated source file.
  • Для обновления исходного кода в репозитории перейдите в корневую папку проекта и выполните cvs update -dP.
  • Если вы создали новый подкаталог в иерархии исходного кода зарегистрируйте его в CVS командой  cvs add {subdirname}.
  • Если Вы создает новый файл исходного кода, перейдите в катало с файлом и зарегистрируйте новый файл командой cvs add {filename}.
  • Если какой то файл Вам больше не понадобится, перейдите в каталог файла и удалите. Далее зарегистрируйте изменение в CVS командой cvs remove {filename}.
  • Если Вы создаете, модифицируете или удаляете исходные файлы, изменения не отобразятся в хранилище сервера. Для сохранения изменений в их текущем состоянии, перейдите в корневой каталог и выполните  cvs commit. Вам будет предложено написать краткое описание произведенных изменений с сохранением их  с новыми версиями исходных файлов
CVS, like other source code control systems, has many additional features (such as the ability to tag the files that made up a particular release, and support for multiple development branches that can later be merged). See the links and references in the Introduction for more information.  CVS, как и другие системы управления исходным кодом, имеет много дополнительных возможностей (такие как пометка файлов соответствующийх определенному релизу, и поддержка нескольких ветвей разработки, которые позже могут быть объеденены). Для более полной информации смотрите Введение.

BUILD.XML Configuration File

Конфигурационный файл BUILD.XML
We will be using the ant tool to manage the compilation of our Java source code files, and creation of the deployment hierarchy. Ant operates under the control of a build file, normally called build.xml, that defines the processing steps required. This file is stored in the top-level directory of your source code hierarchy, and should be checked in to your source code control system. Like a Makefile, the build.xml file provides several «targets» that support optional development activities (such as creating the associated Javadoc documentation, erasing the deployment home directory so you can build your project from scratch, or creating the web application archive file so you can distribute your application. A well-constructed build.xml file will contain internal documentation describing the targets that are designed for use by the developer, versus those targets used internally. To ask Ant to display the project documentation, change to the directory containing the build.xml file and type:

ant -projecthelp

To give you a head start, a basic build.xml file is provided that you can customize and install in the project source directory for your application. This file includes comments that describe the various targets that can be executed. Briefly, the following targets are generally provided:

  Мы будем использовать утилиту ant для управления компиляцией файлов исходного кода Java и для создания разворачиваемой иерархии. ant работает под управлением файла сборки, обычно называемый build.xml, который определяет требуемые этапы обработки. Этот файл хранится в корне иерархии исходного кода, и должен быть проверен системой контроля исходного кода.Файл build.xml поддерживает несколько опциональных целей (таких как создание документации Javadoc, очистка домашнего каталога развертывания приложения для сборки проекта «с нуля», или создания для распространения архива web приложения). Хорошо сконструированный файл build.xml содержит описание внутренней документации предназначенной для использования разработчиком для внутренних целей. Для запроса вывода документации проекта выберите директорию содержащую файл build.xml и наберите:

ant -projecthelp

Предлагается базовый файл build.xml который может быть использован в качестве основы для Вашего проекта. Это файл включает комментарии которые описывают различные цели (таргеты) файла которые могут быть настроены.
  • clean — This target deletes any existing build and dist directories, so that they can be reconstructed from scratch. This allows you to guarantee that you have not made source code modifications that will result in problems at runtime due to not recompiling all affected classes.
  • compile — This target is used to compile any source code that has been changed since the last time compilation took place. The resulting class files are created in the WEB-INF/classes subdirectory of your build directory, exactly where the structure of a web application requires them to be. Because this command is executed so often during development, it is normally made the «default» target so that a simple ant command will execute it.
  • all — This target is a short cut for running the clean target, followed by the compile target. Thus, it guarantees that you will recompile the entire application, to ensure that you have not unknowingly introduced any incompatible changes.
  • javadoc — This target creates Javadoc API documentation for the Java classes in this web application. The example build.xml file assumes you want to include the API documentation with your app distribution, so it generates the docs in a subdirectory of the dist directory. Because you normally do not need to generate the Javadocs on every compilation, this target is usually a dependency of the dist target, but not of the compile target.
  • dist — This target creates a distribution directory for your application, including any required documentation, the Javadocs for your Java classes, and a web application archive (WAR) file that will be delivered to system administrators who wish to install your application. Because this target also depends on the deploy target, the web application archive will have also picked up any external dependencies that were included at deployment time.
  • clean — этот узел удаляет любой существующий каталог build и dist, потому что они могут быть созданы с нуля. Это позволяет нет ь не сохраненных файлов исходного кода, которые может привести к проблемам на стадии выполнении из за не пере компилированных классов.
  • compile — используется для пере компиляции исходного кода который бил изменен с момента последней компиляции. В результате, файлы классов размещаются в подкаталоге WEB-INF/classes каталога сборки, именно там где они должны располагаться согласно структуре web приложения. В связи с тем что эта команда выполняется очень часто что простая команда ant будет выполнять именно ее по умолчанию.
  • all — Это сокращенная команда выполняющая clean команду, после команды compile. Это гарантирует пере компиляцию приложения целиком для исключения возможных несовместимых изменений.
  • javadoc — Создает Javadoc API документацию для Java классов web приложения. В примере файла build.xml предполагается, что вы хотите включить документацию вашего приложения, поэтому оно помещает документы в каталог d.ist. Так как обычно нет необходимости в генерации документации при каждой компиляции, эта команда, как правило, зависит от команды dist, не не от команды compile.
  • dist — Эта команда создает дистрибутив для Вашего приложения, включая всю требуемую документацию Javadoc для классов Java, и архив web приложения (WAR файл) который будет предоставляться системному администратору пожелавшему установить ваше Web приложение.. Так как эта команда зависит от команды deploy, архив web приложения так же будет включать любые внешние зависимости включение на стадии разработки.
For interactive development and testing of your web application using Tomcat, the following additional targets are defined:  Для активной разработки и тестирования web приложения использую Tomcat определены следующие дополнительные команды
  • install — Tell the currently running Tomcat to make the application you are developing immediately available for execution and testing. This action does not require Tomcat to be restarted, but it is also not remembered after Tomcat is restarted the next time.
  • reload — Once the application is installed, you can continue to make changes and recompile using the compile target. Tomcat will automatically recognize changes made to JSP pages, but not to servlet or JavaBean classes — this command will tell Tomcat to restart the currently installed application so that such changes are recognized.
  • remove — When you have completed your development and testing activities, you can optionally tell Tomcat to remove this application from service.
  • install — сообщить Tomcat о необходимости сделать немедленно приложение доступным для выполнения и тестирования. Это действие не требует перезапуска Tomcat, но оно не сохранит приложение после его перезапуска.
  • reload — После того, как программа установлена, Вы можете вносить изменения в ее исходный код. Tomcat автоматически распознает изменения в JSP страницах, но не в сервлетах и JavaBean классах. Команда сообщает Tomcat о необходимости перезапустить приложения для применения изменений.
  • remove — После завершения разработки и тестирования приложения вы можете сообщить Tomcat удалить приложение из сервиса.
Using the development and testing targets requires some additional one-time setup that is described on the next page.  Использование команд тестирования и разработки требуется некоторая разовая настройка, описанная на в следующем разделе

To be continued …

Закладка Постоянная ссылка.
Комментарии для сайта Cackle