<?xml version="1.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.
-->

<document>

 <properties>
  <title>Turbine Services - Unique ID Service</title>
 </properties>

<body>

<section name="Unique ID Service">

<p>
The UniqueId Service is an identifier generator that provides access to Turbine instance specific ID's in several different formats.

</p>

</section>

<section name="Configuration">

<source><![CDATA[
# -------------------------------------------------------------------
#
#  S E R V I C E S
#
# -------------------------------------------------------------------
# Classes for Turbine Services should be defined here.
# Format: services.[name].classname=[implementing class]
#
# To specify properties of a service use the following syntax:
# service.[name].[property]=[value]

services.UniqueIdService.classname=org.apache.turbine.services.uniqueid.TurbineUniqueIdService
.
.
.
]]></source>

</section>

<section name="Usage">

<p>
The Facade class, TurbineUniqueId, exposes three methods that produce unique identifiers:
</p>

<li>getInstanceId() returns an identifier for this Turbine instance that is unique both on the server and worldwide.</li>
<li>getPseudorandomId() returns a unique identifier that looks like random data.</li>
<li>getUniqueId() returns an identifier that is unique within this instance but does not have random-like appearance.</li>

<p>
As an example of the output for these Id's, the following is a screen:
</p>

<source><![CDATA[
 public class IdExample extends VelocityScreen
 {


    public void doBuildTemplate(RunData data , Context context)
        throws Exception
    {

        context.put("instanceid", TurbineUniqueId.getInstanceId());
        context.put("pseudorandomid", TurbineUniqueId.getPseudorandomId());
        context.put("uniqueid", TurbineUniqueId.getUniqueId());

        super.doBuildTemplate(data,context);


    }
 }
]]></source>

<p>
With the Velocity template IdExample.vm being:
</p>

<source><![CDATA[

 InstanceId() Output example  = $instanceid

 <br />

 PseudorandomId() Output example  = $pseudorandom

 <br />

 UniqueId() Output example  = $uniqueid

]]></source>

<p>
The output is:
</p>

<source><![CDATA[

 InstanceId() Output example  = EC77218EC1291E714260FDF04BCB5008
 PseudorandomId() Output example  = otzhj954w1
 UniqueId() Output example  = 00000000

]]></source>


<p>
Internally Turbine uses the service for naming of temporary files stored on the server as part of the Upload Service. The FileItem is named with the getInstanceId() method to avoid temporary file clashes until the system retrieves the file.
</p>

</section>

</body>
</document>
