* Loads a PSML document from disk bypassing the cache
     * 
     * @param locator
     * @return PSML document from disk
     */
    public PSMLDocument refresh(ProfileLocator locator)
    {
        if (logger.isDebugEnabled())
        {
            logger.debug("CastorPsmlManagerService: psml document refreshed from disk: " + locator.getPath());
        }
        return getDocument(locator, false);
    }

    /**
     * Load a PSMLDOcument from disk
     *
     * @param fileOrUrl a String representing either an absolute URL or an
     * absolute filepath
     */
    protected PSMLDocument loadDocument(String fileOrUrl)
    {
        PSMLDocument doc = null;

        if (fileOrUrl!=null)
        {
            if (!fileOrUrl.endsWith(DEFAULT_EXT))
            {
                fileOrUrl = fileOrUrl.concat(DEFAULT_EXT);
            }

            // load the document and add it to the watcher
            // we'll assume the name is the the location of the file

            File f = getFile(fileOrUrl);
            if (null == f)
                return null;

            doc = new BasePSMLDocument();
            doc.setName(fileOrUrl);

            // now that we have a file reference, try to load the serialized PSML
            Portlets portlets = null;
            try
            {
                DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
                DocumentBuilder builder = dbfactory.newDocumentBuilder();

                Document d = builder.parse(f);

                Unmarshaller unmarshaller = new Unmarshaller(this.mapping);
                portlets = (Portlets)unmarshaller.unmarshal((Node) d);

                doc.setPortlets(portlets);

            }
            catch (IOException e)
            {
                logger.error("PSMLManager: Could not load the file "+f.getAbsolutePath(), e);
                doc = null;
            }
            catch (MarshalException e)
            {
                logger.error("PSMLManager: Could not unmarshal the file "+f.getAbsolutePath(), e);
                doc = null;
            }
            catch (MappingException e)
            {
                logger.error("PSMLManager: Could not unmarshal the file "+f.getAbsolutePath(), e);
                doc = null;
            }
            catch (ValidationException e)
            {
                logger.error("PSMLManager: document "+f.getAbsolutePath()+" is not valid", e);
                doc = null;
            }
            catch (ParserConfigurationException e)
            {
                logger.error("PSMLManager: Could not load the file "+f.getAbsolutePath(), e);
                doc = null;
            }
            catch (SAXException e)
            {
                logger.error("PSMLManager: Could not load the file "+f.getAbsolutePath(), e);
                doc = null;
            }
        }

        return doc;
    }

    /** Store the PSML document on disk, using its locator
     *
     * @param profile the profile locator description.
     * @return true if the operation succeeded
     */
    public boolean store(Profile profile)
    {
        PSMLDocument doc = profile.getDocument();

        File base = this.rootDir;
        String path = mapLocatorToFile(profile);

        File file = new File(base, path);
        String fullpath = null;

        try
        {
            fullpath = file.getCanonicalPath();
        }
        catch (IOException e)
        {
            logger.error("PSMLManager: unable to resolve file path for "+ file);
        }

        boolean ok = saveDocument(fullpath, doc);

        // update it in cache
        synchronized (documents)
        {
            try
            {
                documents.put(fullpath, profile);
            }
            catch (IOException e)
            {
                logger.error("Error storing document", e);
            }
        }

        return ok;
    }

    /** Save the PSML document on disk, using its name as filepath
     * @deprecated
     * @param doc the document to save
     */
    public boolean saveDocument(PSMLDocument doc)
    {
        return saveDocument(doc.getName(), doc);
    }

    /** Save the PSML document on disk to the specififed fileOrUrl
     *
     * @param fileOrUrl a String representing either an absolute URL
     * or an absolute filepath
     * @param doc the document to save
     */
    public boolean saveDocument(String fileOrUrl, PSMLDocument doc)
    {
        boolean success = false;

        if (doc == null) return false;
        File f = getFile(fileOrUrl);
        if (f == null)
        {
            f = new File(fileOrUrl);
        }

        OutputStreamWriter writer = null;
        FileOutputStream fos = null;
        try
        {
            String encoding = this.defaultEncoding;
            fos = new FileOutputStream(f);
            writer = new OutputStreamWriter(fos, encoding);

            save(writer, doc.getPortlets());
            success = true;
        }
        catch (MarshalException e)
        {
            logger.error("PSMLManager: Could not marshal the file "+f.getAbsolutePath(), e);
        }
        catch (MappingException e)
        {
            logger.error("PSMLManager: Could not marshal the file "+f.getAbsolutePath(), e);
        }
        catch (ValidationException e)
        {
            logger.error("PSMLManager: document "+f.getAbsolutePath()+" is not valid", e);
        }
        catch (IOException e)
        {
            logger.error("PSMLManager: Could not save the file "+f.getAbsolutePath(), e);
        }
        catch (Exception e)
        {
            logger.error("PSMLManager: Error while saving  "+f.getAbsolutePath(), e);
        }
        finally
        {
            try { writer.close(); } catch (IOException e) {}
            try { if(fos != null) { fos.close(); } } catch (IOException e) {}
        }

        return success;
    }

    /** Deserializes a PSML structure read from the reader using Castor
     *  XML unmarshaller
     *
     * @param reader the reader to load the PSML from
     * @param the loaded portlets structure or null
     */
    protected Portlets load(Reader reader)
        throws IOException, MarshalException, ValidationException, MappingException
    {
        Unmarshaller unmarshaller = new Unmarshaller(this.mapping);
        Portlets portlets = (Portlets)unmarshaller.unmarshal(reader);
        return portlets;
    }

    protected void loadMapping()
        throws InitializationException
    {
        // test the mapping file and create the mapping object

        if (mapFile != null)
        {
            File map = new File(mapFile);
            if (logger.isDebugEnabled())
            {
                logger.debug("PSMLManager: Loading psml mapping file "+mapFile);
            }
            if (map.exists() && map.isFile() && map.canRead())
            {
                try
                {
                    mapping = new Mapping();
                    InputSource is = new InputSource( new FileReader(map) );
                    is.setSystemId( mapFile );
                    mapping.loadMapping( is );
                }
                catch (Exception e)
                {
                    logger.error("PSMLManager: Error in psml mapping creation", e);
                    throw new InitializationException("Error in mapping",e);
                }
            }
            else
            {
                throw new InitializationException("PSML Mapping not found or not a file or unreadable: "+mapFile);
            }
        }
    }

    /** Serializes a PSML structure using the specified writer with Castor
     *  XML marshaller and a Xerces serializer for pretty printing
     *
     * @param writer the writer to use for serialization
     * @param portlets the structure to save
     */
    protected void save(Writer writer, Portlets portlets)
        throws IOException, MarshalException, ValidationException, MappingException
    {
        String encoding = this.defaultEncoding;

        if (portlets != null)
        {
            format.setEncoding(encoding);
            Serializer serializer = new XMLSerializer(writer, format);
            Marshaller marshaller = new Marshaller(serializer.asDocumentHandler());
            marshaller.setMapping(this.mapping);
            marshaller.marshal(portlets);
        }
    }

    /** Tests wether the passed argument is an URL string or a file name
     *  and returns the corresponding file object, using diskcache for
     *  remote URLs
     *
     *  @param fileOrUrl the URL string or file path
     *  @return a File object. This file may not exist on disk.
     */
    protected File getFile(String fileOrUrl)
    {
        File f = null;

        f = new File(fileOrUrl);

        if (f.exists())
        {
            return f;
        }

        return null;
    }

    /** Create a new document.
     *
     * @param profile The description and default value for the new document.
     * @return The newly created document;
     */
    public PSMLDocument createDocument( Profile profile )
    {
        File base = this.rootDir;
        String path = mapLocatorToFile((ProfileLocator)profile);

        if (logger.isDebugEnabled())
        {
            logger.debug("PSMLManager: Create document for profile " + profile +", calculated path: " + path);
        }

        File file = new File(base, path);
        String name = null;

        try
        {
            name = file.getCanonicalPath();
        }
        catch (IOException e)
        {
            logger.error("PSMLManager: unable to resolve file path for "+ file);
        }

        PSMLDocument template = profile.getDocument();
        PSMLDocument doc = new BasePSMLDocument( name, template.getPortlets() );
        try
        {
            String parent = file.getParent();
            File filePath = new File(parent);
            filePath.mkdirs();
            if (template.getName() != null)
            {
                try
                {
                    File source = new File(template.getName());
                    if (source.exists())
                    {
                        FileCopy.copy( template.getName(), name );
                    }
                }
                catch (Exception e)
                {}
            }
            else
            {
                doc.setName(name);
            }
            saveDocument(doc);
        }
        catch (Exception e)
        {
            logger.error("PSMLManager: Failed to save document: " , e);
        }
        return doc;
    }

    /** Given a ordered list of locators, find the first document matching
     *  a profile locator, starting from the beginning of the list and working
     *  to the end.
     *
     * @param locator The ordered list of profile locators.
     */
    public PSMLDocument getDocument( List locators )
    {
        PSMLDocument doc=null;

        Iterator i = locators.iterator();
        while ((doc==null)&&(i.hasNext()))
        {
            doc=getDocument((ProfileLocator)i.next());
        }

        return doc;
    }

    /** Removes a document.
     *
     * @param locator The description of the profile resource to be removed.
     */
    public void removeDocument( ProfileLocator locator )
    {
        // remove a single document
        String fileName = mapLocatorToFile(locator);

        File base = this.rootDir;
        File file = new File(base, fileName);
        String name = null;

        try
        {
            name = file.getCanonicalPath();
        }
        catch (IOException e)
        {
            logger.error("PSMLManager: unable to resolve file path for "+ file);
        }


        synchronized (documents)
        {