diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html | 224 |
1 files changed, 0 insertions, 224 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html deleted file mode 100644 index 3adfa80c..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html +++ /dev/null @@ -1,224 +0,0 @@ -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html><head><link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> -<title>XmlNamespaceSupport</title></head> - <body> - <h2><a name="namespace">XML Namespace Support</a></h2> - Apache Ant 1.6 introduces support for XML namespaces. - <h3>History</h3> - - <p> - All releases of Ant prior to Ant 1.6 do not support XML namespaces. - No support basically implies two things here: - </p> - <ul> - <li> Element names correspond to the "qname" of the tags, which is - usually the same as the local name. But if the build file writer uses - colons in names of defined tasks/types, those become part of the - element name. Turning on namespace support gives colon-separated - prefixes in tag names a special meaning, and thus build files using - colons in user-defined tasks and types will break. - </li> - <li> Attributes with the names 'xmlns' and 'xmlns:<code><prefix></code>' - are not treated specially, which means that custom tasks and types have - actually been able to use such attributes as parameter names. Again, - such tasks/types are going to break when namespace support is enabled - on the parser. - </li> - </ul> - <p>Use of colons in element names has been discouraged in the past, - and using any attribute starting with "xml" is actually strongly - discouraged by the XML spec to reserve such names for future use. - </p> - <h3>Motivation</h3> - - <p>In build files using a lot of custom and third-party tasks, it is - easy to get into name conflicts. When individual types are defined, the - build file writer can do some namespacing manually (for example, using - "tomcat-deploy" instead of just "deploy"). But when defining whole - libraries of types using the <code><typedef></code> 'resource' attribute, the - build file writer has no chance to override or even prefix the names - supplied by the library. </p> - <h3>Assigning Namespaces</h3> - - <p> - Adding a 'prefix' attribute to <code><typedef></code> might have been enough, - but XML already has a well-known method for namespacing. Thus, instead - of adding a 'prefix' attribute, the <code><typedef></code> and <code><taskdef></code> - tasks get a 'uri' attribute, which stores the URI of the XML namespace - with which the type should be associated: - </p><pre> <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> - <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - ... - </my:task> -</pre> - <p>As the above example demonstrates, the namespace URI needs to be - specified at least twice: one time as the value of the 'uri' attribute, - and another time to actually map the namespace to occurrences of - elements from that namespace, by using the 'xmlns' attribute. This - mapping can happen at any level in the build file: - </p><pre> <project name="test" xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> - <my:task> - ... - </my:task> - </project> -</pre> - <p> - Use of a namespace prefix is of course optional. Therefore - the example could also look like this: - </p><pre> <project name="test"> - <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> - <task xmlns="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - ... - </task> - </project> -</pre> - <p> - Here, the namespace is set as the default namespace for the <code><task></code> - element and all its descendants. - </p> - <h3>Default namespace</h3> - <p> - The default namespace used by Ant is "antlib:org.apache.tools.ant". - </p> - <pre> -<typedef resource="org/example/tasks.properties" uri="antlib:org.apache.tools.ant"/> -<task> - .... -</task> - </pre> - - - - <h3>Namespaces and Nested Elements</h3> - - <p> - Almost always in Ant 1.6, elements nested inside a namespaced - element have the same namespace as their parent. So if 'task' in the - example above allowed a nested 'config' element, the build file snippet - would look like this: - </p><pre> <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> - <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - <my:config a="foo" b="bar"/> - ... - </my:task> -</pre> - <p>If the element allows or requires a lot of nested elements, the - prefix needs to be used for every nested element. Making the namespace - the default can reduce the verbosity of the script: - </p><pre> <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> - <task xmlns="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - <config a="foo" b="bar"/> - ... - </task> - </pre> - <p> - From Ant 1.6.2, elements nested inside a namespaced element may also be - in Ant's default namespace. This means that the following is now allowed: - </p> - </p><pre> <typedef resource="org/example/tasks.properties" - uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> - <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - <config a="foo" b="bar"/> - ... - </my:task> -</pre> - - <h3>Namespaces and Attributes</h3> - - <p> - Attributes are only used to configure the element they belong to if: - </p> - <ul> - <li> they have no namespace (note that the default namespace does *not* apply to attributes) - </li> - <li> they are in the same namespace as the element they belong to - </li> - </ul> - <p> - In Ant 1.9.1 two attribute namespaces <code>ant:if</code> and <code>ant:unless</code> were added - to allow you to insert elements conditionally. - </p> - <p> - Other attributes are simply ignored. - </p> - <p> - This means that both: - </p> - <p> - </p><pre> <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - <my:config a="foo" b="bar"/> - ... - </my:task> -</pre> - <p> - and - </p> - <pre> <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> - <my:config my:a="foo" my:b="bar"/> - ... - </my:task> -</pre> - <p> - result in the parameters "a" and "b" being used as parameters to configure the nested "config" element. - </p> - <p>It also means that you can use attributes from other namespaces - to markup the build file with extra metadata, such as RDF and - XML-Schema (whether that's a good thing or not). The same is not true - for elements from unknown namespaces, which result in a error. - </p> - <h3>Mixing Elements from Different Namespaces</h3> - - <p>Now comes the difficult part: elements from different namespaces can - be woven together under certain circumstances. This has a lot to do - with the Ant 1.6 - <a href="../develop.html#nestedtype">add type introspection rules</a>: - Ant types and tasks are now free to accept arbitrary named types as - nested elements, as long as the concrete type implements the interface - expected by the task/type. The most obvious example for this is the - <code><condition></code> task, which supports various nested conditions, all - of which extend the interface <tt>Condition</tt>. To integrate a - custom condition in Ant, you can now simply <code><typedef></code> the - condition, and then use it anywhere nested conditions are allowed - (assuming the containing element has a generic <tt>add(Condition)</tt> or <tt>addConfigured(Condition)</tt> method): -</p><pre> <typedef resource="org/example/conditions.properties" uri="<a href="http://example.org/conditions">http://example.org/conditions</a>"/> - <condition property="prop" xmlns="<a href="http://example.org/conditions">http://example.org/conditions</a>"> - <and> - <available file="bla.txt"/> - <my:condition a="foo"/> - </and> - </condition> -</pre> - <p> - In Ant 1.6, this feature cannot be used as much as we'd all like to: a - lot of code has not yet been adapted to the new introspection rules, - and elements like Ant's built-in conditions and selectors are not - really types in 1.6. This is expected to change in Ant 1.7. - </p> - <h3>Namespaces and Antlib</h3> - - <p> - The new <a href="antlib.html">AntLib</a> - feature is also very much integrated with the namespace support in Ant - 1.6. Basically, you can "import" Antlibs simply by using a special - scheme for the namespace URI: the <tt>antlib</tt> scheme, which expects the package name in which a special <tt>antlib.xml</tt> file is located. - </p> - -</body> -</html> |