Difference between revisions of "Documentation/DevGuide/Extensions/Extension Identifiers"

From Apache OpenOffice Wiki
Jump to: navigation, search
m
m (need of identifier for OOo 3.3)
 
(13 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{Documentation/DevGuide/ExtensionsTOC
 
{{Documentation/DevGuide/ExtensionsTOC
 
|ShowPrevNext=block
 
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Display Name
+
|PrevPage=Documentation/DevGuide/Extensions/Extension Description
 
|NextPage=Documentation/DevGuide/Extensions/Extension Versions
 
|NextPage=Documentation/DevGuide/Extensions/Extension Versions
 
}}
 
}}
 +
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:Extension Identifiers}}
 
{{DISPLAYTITLE:Extension Identifiers}}
Extensions now have unique identifiers. This removes the previous restriction that no two extensions with identical file names can be deployed. That is, two extensions with same file name but different identifiers can be installed but two extensions with the same identifiers cannot be installed at the same time. In the latter case, the already installed extension will be replaced.
+
Extensions now have unique identifiers. This removes the previous restriction that no two extensions with identical file names can be deployed. That is, two extensions with same file name but different identifiers can be installed but two extensions with the same identifiers cannot be installed at the same time.
  
The identifier plays also an important role for the on-line update. The Extension Manager uses it to determine if there is an update available. Therefore there must not exist two different extensions with the same identifier. This is also the case for extensions which are logically the same but support different platforms. If they did not have different identifiers then the Extension Manager could  update an extension with a new version which does not work on the user's platform.
+
The identifier plays also an important role for the [[Documentation/DevGuide/Extensions/Online_Update_of_Extensions|on-line update]]. When running the on-line update, then the Extension Manager downloads a list of available extensions from the extension repository or from the location determined by the installed extension. The Extension Manager then tries to find an extension with a newer version in this list by comparing the identifier of the installed extensions with the identifier contained in the [[Documentation/DevGuide/Extensions/Description_of_the_Update_Information|update information]]. Therefore the identifier '''MUST''' be unique. This is also the case when two extensions are logically the same but support different platforms. In this case one can achieve this uniqueness by adding a platform string to identifier. The  [[Documentation/DevGuide/Extensions/Target Platform#Generating the Platform String in the Build Environment|'Target Platform']] section describes how this string can be generated in the build environment.
  
 
+
Technically, an extension identifier is a finite sequence of Unicode scalar values. Identifier identity is element-by-element identity of the sequences (no case folding, no normalization, etc.). It is assumed that extension writers cooperate to keep extension identifiers unique. By convention, use lowercase reversed-domain-name syntax (e.g., ''org.openoffice.'') prefixes to generate unique (but still humanly comprehensible) identifiers. When you write an extension, use the reversed domain name of a site you control (and not ''org.openoffice.'') as prefix. Identifiers starting with the prefix ''org.openoffice.legacy.'' are reserved for legacy extensions (see next). The same procedure used to avoid name clashes for extension identifier applies to all unique names in configuration files of extensions (configuration nodes in extendable lists etc.).
Technically, an extension identifier is a finite sequence of Unicode scalar values. Identifier identity is element-by-element identity of the sequences (no case folding, no normalization, etc.). It is assumed that extension writers cooperate to keep extension identifiers unique. By convention, use lowercase reversed-domain-name syntax (e.g., ''org.openoffice.'') prefixes to generate unique (but still humanly comprehensible) identifiers. When you write an extension, use the reversed domain name of a site you control (and not ''org.openoffice.'') as prefix. Identifiers starting with the prefix ''org.openoffice.legacy.'' are reserved for legacy extensions (see next).
+
  
 
The extension identifier is obtained from the ''description.xml'' contained in the extension. If the extension does not specify such an explicit identifier, then an implicit identifier is generated by prepending ''org.openoffice.legacy.'' to the (obvious sequence of Unicode scalar values representing the) file name of the extension. (Uniqueness of identifiers is then guaranteed by the assumption underlying legacy extension management that no two legacy extensions have the same file name.)
 
The extension identifier is obtained from the ''description.xml'' contained in the extension. If the extension does not specify such an explicit identifier, then an implicit identifier is generated by prepending ''org.openoffice.legacy.'' to the (obvious sequence of Unicode scalar values representing the) file name of the extension. (Uniqueness of identifiers is then guaranteed by the assumption underlying legacy extension management that no two legacy extensions have the same file name.)
 +
 +
'''As of OOo 3.3''' providing an identifier is necessary for bundled and shared extensions (see [[Documentation/DevGuide/Extensions/Processing_Extensions#Removing_a_shared_extension|Processing Extensions]]).
 +
 +
 +
'''See also'''
 +
*[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/identifier|XML description for description.xml]]
 +
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]
 +
  
 
{{PDL1}}
 
{{PDL1}}
[[Category: Extensions]]
+
 
 +
[[Category:Documentation/Developer's Guide/Extensions]]

Latest revision as of 05:33, 9 June 2010



Extensions now have unique identifiers. This removes the previous restriction that no two extensions with identical file names can be deployed. That is, two extensions with same file name but different identifiers can be installed but two extensions with the same identifiers cannot be installed at the same time.

The identifier plays also an important role for the on-line update. When running the on-line update, then the Extension Manager downloads a list of available extensions from the extension repository or from the location determined by the installed extension. The Extension Manager then tries to find an extension with a newer version in this list by comparing the identifier of the installed extensions with the identifier contained in the update information. Therefore the identifier MUST be unique. This is also the case when two extensions are logically the same but support different platforms. In this case one can achieve this uniqueness by adding a platform string to identifier. The 'Target Platform' section describes how this string can be generated in the build environment.

Technically, an extension identifier is a finite sequence of Unicode scalar values. Identifier identity is element-by-element identity of the sequences (no case folding, no normalization, etc.). It is assumed that extension writers cooperate to keep extension identifiers unique. By convention, use lowercase reversed-domain-name syntax (e.g., org.openoffice.) prefixes to generate unique (but still humanly comprehensible) identifiers. When you write an extension, use the reversed domain name of a site you control (and not org.openoffice.) as prefix. Identifiers starting with the prefix org.openoffice.legacy. are reserved for legacy extensions (see next). The same procedure used to avoid name clashes for extension identifier applies to all unique names in configuration files of extensions (configuration nodes in extendable lists etc.).

The extension identifier is obtained from the description.xml contained in the extension. If the extension does not specify such an explicit identifier, then an implicit identifier is generated by prepending org.openoffice.legacy. to the (obvious sequence of Unicode scalar values representing the) file name of the extension. (Uniqueness of identifiers is then guaranteed by the assumption underlying legacy extension management that no two legacy extensions have the same file name.)

As of OOo 3.3 providing an identifier is necessary for bundled and shared extensions (see Processing Extensions).


See also


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages