將任務或資料類型定義新增至目前的專案,以便在目前的專案中使用此新類型或任務。
任務是任何延伸 org.apache.tools.ant.Task
的類別,或可以使用適配器類別作為任務進行適配。
資料類型是可以在專案層級定義並透過其 id 屬性參照的項目,例如 路徑 或 檔案集。自訂資料類型通常需要自訂任務才能善加利用。
需要兩個屬性才能建立定義:識別此資料類型唯一的名稱,以及實作此類型的類別(包括其套件名稱)的全名。
您也可以使用 file 或 resource 屬性一次定義一組定義。這些屬性指向 Java 屬性檔案或 XML 格式的檔案。
對於屬性檔案,每行定義一個資料類型,格式如下
typename=fully.qualified.java.classname
XML 格式在 Antlib 區段中說明。
如果您定義的任務或類型與多個 taskdef
或 typedef
任務共用同一個類別路徑,對應的類別將由不同的 Java ClassLoader 載入。透過不同的 ClassLoader 載入的兩個同名類別,在 JVM 的觀點來看並非同一個類別,它們不共用靜態變數,而且這些類別的執行個體無法存取同名的「另一個類別」所定義執行個體的私有方法或屬性。它們甚至不屬於同一個 Java 套件,也無法存取套件私有程式碼。
載入多個任務/類型的方式,讓它們能透過共用 Java 程式碼彼此合作,最佳的方式是使用 resource 屬性與 antlib
描述詞。如果無法這樣做,第二個最佳選項是使用 loaderref 屬性,並為每個 typedef
/taskdef
指定相同的名稱—這樣一來,這些類別將共用同一個 ClassLoader
。請注意,typedef
/taskdef
任務必須使用相同的類別路徑定義(這包括路徑組件的順序),才能讓 loaderref 屬性運作。
屬性 | 說明 | 必要 |
---|---|---|
name | 資料類型的名稱 | 是,除非已指定 file 或 resource 屬性。 |
classname | 實作資料類型的完整類別名稱 | |
file | 要從中載入定義的檔案名稱。 | 否 |
resource | 載入定義的資源名稱。如果在類別路徑中找到多個此名稱的資源,且格式為屬性,則會載入第一個資源;否則,將載入所有此類資源。 |
否 |
格式 | 檔案或資源的格式。值為屬性"或 xml。如果值為 屬性,則檔案/資源為包含名稱-類別名稱對的屬性檔案。如果值為 xml,則檔案/資源為根據Antlib建構的 XML 檔案/資源。預設為 屬性,除非檔案/資源名稱以.xml結尾,在此情況下,格式屬性的值為 xml。自 Ant 1.6 起 |
否 |
類別路徑 | 在查詢類別名稱時要使用的類別路徑。 | 否 |
類別路徑參考 | 在查詢類別名稱時要使用的類別路徑的參考。 | 否 |
載入器參考 | 用於載入類別的載入器的名稱,由指定的類別路徑建構。使用此功能可讓多個工作/類型使用同一個載入器載入,以便它們可以互相呼叫。自 Ant 1.5 起 | 否 |
錯誤處理 | 在定義類型時發生失敗時執行的動作。值為失敗:導致建置例外狀況; 報告:輸出警告,但繼續執行; 忽略:不執行任何動作。自 Ant 1.6 起,額外的值為 全部失敗:導致全部失敗行為,以及如果找不到資源或檔案,則會針對資源或檔案屬性產生建置例外狀況。 |
否;預設為失敗(自 Ant 1.7 起) |
轉接器 | 用於將已定義類別轉接至另一個介面/類別的類別。轉接器類別必須實作介面org.apache.tools.ant.TypeAdapter 。除非已定義的類別實作/延伸由轉接至屬性定義的類別,否則將使用轉接器類別包裝已定義的類別。如果未設定 轉接至,則將永遠包裝已定義的類別。自 Ant 1.6 起 |
否 |
轉接至 | 此屬性與轉接器屬性搭配使用。如果已定義的類別未實作/延伸此屬性指定的介面/類別,則將使用轉接器類別包裝類別。自 Ant 1.6 起 | 否 |
URI | 此定義應存在的 URI。自 Ant 1.6 起 | 否 |
Typedef
的類別路徑屬性為類似路徑的結構,也可以透過巢狀類別路徑
元素設定。
下列片段定義稱為urlset
的類型。
<typedef name="urlset" classname="com.mydomain.URLSet"/>
資料類型現在可供 Ant 使用。類別com.mydomain.URLSet
實作此類型。
假設一個類別 org.acme.ant.RunnableAdapter
延伸 Task
並實作 org.apache.tools.ant.TypeAdapter
,且在 execute()
方法中呼叫代理物件上的 run()
,就可以將 Runnable
類別用作 Ant 任務。下列片段定義一個名為 runclock
的任務。
<typedef name="runclock" classname="com.acme.ant.RunClock" adapter="org.acme.ant.RunnableAdapter"/>
下列片段顯示如何使用 classpathref 和 loaderref 來載入兩個定義。
<path id="lib.path"> <fileset dir="lib" includes="lib/*.jar"/> </path> <typedef name="filter1" classname="org.acme.filters.Filter1" classpathref="lib.path" loaderref="lib.path.loader"/> <typedef name="filter2" classname="org.acme.filters.Filter2" loaderref="lib.path.loader"/>
如果您想要將 antlib 載入到一個特殊的 XML 名稱空間中,uri 屬性非常重要
<project xmlns:antcontrib="antlib:net.sf.antcontrib"> <taskdef uri="antlib:net.sf.antcontrib" resource="net/sf/antcontrib/antlib.xml" classpath="path/to/ant-contrib.jar"/>
此處的名稱空間宣告 xmlns:antcontrib="antlib:net.sf.antcontrib"
允許 Ant-Contrib Antlib 的任務和類型與 antcontrib 前綴一起使用,例如 <antcontrib:if>
。XML 名稱空間的正常規則適用,您可以在任何元素中宣告前綴,以使其可用於宣告它的元素以及其所有子元素。