Maven用戶指南(4)

命名約定
這部分將簡要的描述項目對象模型(POM)中命名約定。本篇文檔希望可以統一各式各樣jar包命名 方法，這些jar包一般爲java開發者社區廣泛使用。

規則和指南
項目
一個項目必須由一個唯一的的標識，標識由a-z小寫字母和連線號構成，其首字母必須以小寫字母 開頭。

<project>
  <groupId>bar</groupId>
  <artifactId>foo</artifactId>
  ...
</project>
所有項目間的引用都由組id和包id構成。到現在爲止，在POM與此相關的是下面將要（上面提到的？）談到的項目的 依賴聲明。

項目的名稱應該易於閱讀，可用於文檔。

<project>
  <groupId>bar</groupId>
  <artifactId>foo</artifactId>
  <name>The Grand Master Foo</name>
  ...
</project>
項目應該有一個組標識，組標識是名稱的基礎部分。

<project>
  <groupId>bar</groupId>
  <artifactId>foo</artifactId>
  <name>The Grand Master Foo</name>
  ...
</project>
所有項目發佈的包都應基於項目唯一的標識，並且放在基於項目的組id的目錄中。對於上面的 項目來說，假定發佈的包是jar類型的包，我們就會有如下目錄結構：

repository
|
+-- bar
     |-- distribution
     `-- jar
         |-- foo-1.0.jar
         `-- foo-2.0.jar
依賴
一個理想的典型依賴聲明的例子可能會象這樣：

<project>
  <groupId>yourProject</groupId>
  <artifactId>yourArtifact</artifactId>
  <name>Your Groovey Machine</name>
  ...

  <dependencies>

   <dependency>
     <groupId>bar</groupId>
     <artifactId>foo</artifactId>
     <version>1.0</version>
   </dependency>

</dependencies>

</project>
這樣一來，依賴於id爲foo1.0 版本的bar項目 屬於org.foo.bar組。這個依賴會被解析爲本地repository中jar文件。上面 的情形假定發佈的包是基於包id命名的。因此對於上述依賴，Maven就會採用 foo-1.0.jar作爲jar名。

就像用戶反映的那樣，這種理想的方式並不能適應所有的項目。有幾種情形我們必須考慮調整 理想的依賴機制：


發佈的jar包的並未使用項目作爲基礎名，如xercesImpl就是所有發佈的jar包的基礎名 它與gump id和maven中的id都不一樣。
發佈的jar包沒有使用任何版本聲明，如許多commons組件並沒有把版本號作爲包名的一部分。
有些項目即沒有使用項目id作爲基礎名也沒有版本聲明。例如，最壞的情形是Java Activation Framework 的jar包，它沒有遵循其他Sun的命名規則，也沒有在jar包中聲明 版本號，甚至在manifest中都沒有任何版本信息。

在多數情形下，任何例外的情況都可以用 &lt;jar&gt;(可選節點)、或者是重命名來解決。 現在，許多Jarkata的產品在repository已經被重命名，因爲在不久的未來，絕大多數的Jarkarta的 項目將用maven進行構建。但這不是公司政策，我們不需要解決所有情況的問題。

發佈多個包的項目
Maven的依賴機制完全支持任何形式的多項目包。 Maven's dependency mechanism completely supports multiple project artifacts of any given type.

下面的代碼包含了ant的主jar包和optional包加上hypothetical包。


<dependencies>

  <!-- A -->
  <dependency>
    <groupId>ant</groupId>
    <artifactId>ant</artifactId>
    <version>1.4.1</version>
  </dependency>

  <!-- B -->
  <dependency>
    <groupId>ant</groupId>
    <artifactId>ant-optional</artifactId>
    <version>1.4.1</version>
  </dependency>

  <!-- C -->
  <dependency>
    <groupId>ant</groupId>
    <artifactId>poorly-named</artifactId>
    <version>1.4.1</version>
  </dependency>

</dependencies>
所以A), B) 和 C)實際上是指向屬於同一組的單個包的指針，這就是說，一個單獨的依賴就是對某個組中的某個 包的引用。目前artifact如果沒有特別說明的話，一般指的是jar包。但是依賴也可能是一個war文件或一個 發行包。我們試圖在提供多數情況下(構建大多需要jar包)使用的缺省方式的同時，也顧及靈活性。

遠程Repository佈局
這部分文檔將對Maven的遠程repositories做一個概要的說明。目前，主repository位於 Ibiblio，但是你也可以自己創建一 個遠程repositories，其結果描述可以在這部分文檔中找到。

任何獨立的項目在repository都有自己的目錄。每個項目有一個唯一的項目id和同名目錄， 項目的發行包就放在這個目錄中。

項目的目錄中可以存放各種各樣的artifacts，目前最爲廣泛使用的兩種類型是jar包和發行包 下面是一個遠程repository快照：

repository
|
|-- ant
|   |-- distribution
|   `-- jars
|       |-- ant-1.4.1.jar
|       `-- ant-optional-1.4.1.jar
+-- jsse
|-- distribution
`-- jars
     |-- jsse.jar
     |-- jcert.jar
     `-- jnet.jar
本地Repository佈局
應該有一個接口集合的緊湊實現使本地repository目錄結構更加隨意一些。現在我只使用 了一個類來實現，顯得有些臃腫。我還是認爲本地和遠程repositories應保持相同的結構 但是爲了使用更樂於使用，我開始設計一些接口，用於滿足用戶自己安排自己本地Repository 佈局，相似的遠程Repositor也在設計中。儘管目前本地repository仍與遠程repository 完全一致，我希望聽到更多的用戶反饋，以促進這些接口的開發，或者完全拋棄它。

生成項目站點
Maven可以爲項目產生一個完成的web站點。這個web站點將包含各種各樣、由許多Maven插件 產生的報告，如javadocs，代碼度量，單元測試，changlog，及其它... 本節文檔接下來的 部分將闡述Maven支持的站點定製選項。

顏色
考慮到一致性，缺省情況下，所有Maven產生的站點都使用相似的外觀。這使用戶一眼就能 認出由Maven產生的站點，產生熟悉的感覺，更加方便信息的獲取。當然，Maven開發組也 考慮到用戶可能會希望定製他們的站點。修改Maven產生的站點，最簡單的方法是指定你要 使用的顏色搭配。這只需要在project.properties簡單的設置適當的屬性 即可。下面是所有可用的屬性描述在 xdoc plugin。

風格
如果你感覺顏色太過於簡單，無法滿足你的要求，你可以用自己的stylesheet。爲了重載 在${basedir}/xdocs/stylesheets/中的maven.css stylesheet，你可以通過設置maven.javadoc.stylesheet 屬性來指定你的 javadoc風格。

報告
最後，如果你希望定製哪些報告需要自動產生，你需要在你的項目描述中包含 reports 標籤庫。 到目前爲止，如果沒有reports標籤指定，所有插件報告都會產生。這個標籤 允許你選擇產生哪些報告而排斥另外一些報告，而且允許你安排順序。

目前的標準 報告集在xdoc中是硬編碼實現的，它們是：

maven-changelog-plugin
maven-changes-plugin
maven-checkstyle-plugin
maven-developer-activity-plugin
maven-file-activity-plugin
maven-javadoc-plugin
maven-jdepend-plugin
maven-junit-report-plugin
maven-jxr-plugin
maven-license-plugin
maven-linkcheck-plugin
maven-pmd-plugin
maven-tasklist-plugin

      如果你希望產生缺省的報告，但是還想增加或刪除一兩個，最好的方法是：給 xdoc:register-reports目標寫一個前置目標(postGoal)。

<postGoal name="xdoc:register-reports">
  <attainGoal name="maven-changelog-plugin:deregister"/>  
  <attainGoal name="maven-myown-plugin:register"/>  
</postGoal>

        排除所有Maven產生的內容
某些情況下，用戶需要構建只有文檔的站點，或是構建聚合許多子項目的站點，但不希望 在站點上有個整體“項目文檔”導航條。設置 maven.xdoc.includeProjectDocumentation屬性值爲no 即可解決這一問題。缺省的，Maven會包含“項目文檔”導航條，下面掛的是許多Maven 生成的報告。