clientmodifications.java

实现了SyncML无线同步协议

/**
 * Copyright (C) 2003-2004 Funambol
 *
 *  This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */

package sync4j.framework.protocol;

import java.util.List;
import java.util.ArrayList;

import sync4j.framework.core.*;
import sync4j.framework.database.Database;

import sync4j.framework.protocol.ProtocolUtil;
import sync4j.framework.protocol.v11.ClientModificationsRequirements;

/**
 * Represents a Client Modification package of the SyncML protocol.
 *
 *  The class is designed to be used in two times. First a <i>ClientModification</i>
 *  is created and checked for validity and compliancy with the protocol. Than
 *  <i>getResponse()</i> can be used to get a response message for the given
 *  request. During the request validation process some information about the
 *  request message are cached into instance variables and used in <i>getResponse()</i>.<br>
 *
 * @author  Stefano Fornari @ Funambol
 *
 * @version $Id: ClientModifications.java,v 1.2 2004/04/29 07:45:49 luigiafassina Exp $
 */
public class ClientModifications 
extends SyncPackage 
implements Flags {
    
    // ------------------------------------------------------------ Constructors
       
    /** Constructors. It creates a new instance from the message header and body
     * plus the databases to synchronize.
     * It also checks if the requirements specified by the SyncML protocol are
     * met; if not a Sync4jException is thrown.
     * @param syncHeader the header of the syncronization packet
     * @param syncBody the body of the syncronization packet
     * @param syncDb the array of databases to be synchronized
     * @throws Sync4jException in case SyncML requiremets are not respected
     */
    public ClientModifications(final      SyncHdr  syncHeader,
    						   final      SyncBody   syncBody  ,
    						   Database[] syncDb               )
    throws Sync4jException {
        super(syncHeader, syncBody);
        checkRequirements();
        databases = syncDb;
    }
    
    // -------------------------------------------------------------- Properties

    /**
     * Has the server sent its capabilities and is expecting a response? 
     * If yes, <i>serverCapabilitiesCmdId</i> is set to the id of the Put command
     * sent by the server. If not, <i>serverCapabilitiesCmdId</i> is empty.
     */
    private CmdID serverCapabilitiesCmdId = null;
    
    /** 
     * Returns the serverCapabilitiesCmdId property.
     *
     * @return the serverCapabilitiesCmdId property.
     */
    public CmdID getServerCapabilitiesCmdId() {
        return this.serverCapabilitiesCmdId;
    }
    
    /** 
     * Sets the serverCapabilitiesCmdId property.
     *
     * @param serverCapabilitiesCmdId new value
     */
    public void setServerCapabilitiesCmdId(CmdID serverCapabilitiesCmdId) {
        this.serverCapabilitiesCmdId = serverCapabilitiesCmdId;
    }
    
    /**
     * Has the server requested client capabilities? 
     * If yes, <i>clientCapabilitiesCmdId</i> is set to the id of the Get command
     * sent by the server. If not, <i>clientCapabilitiesCmdId</i> is empty.
     */
    private CmdID clientCapabilitiesCmdId = null;
    
    /** 
     * Returns the clientCapabilitiesCmdId property.
     *
     * @return the clientCapabilitiesCmdId property.
     */
    public CmdID getClientCapabilitiesCmdId() {
        return this.clientCapabilitiesCmdId;
    }
    
    /**
     * Sets the serverCapabilitiesCmdId property.
     * @param clientCapabilitiesCmdId new value
     */
    public void setClientCapabilitiesCmdId(CmdID clientCapabilitiesCmdId) {
        this.clientCapabilitiesCmdId = clientCapabilitiesCmdId;
    }
    
    /**
     * The results command in response to the request of client capabilities
     */
    private Results clientCapabilitiesResults = null;
    
    /** 
     * Returns the clientCapabilitiesResults property.
     *
     * @return the clientCapabilitiesResults property.
     */
    public Results getClientCapabilitiesResults() {
        return this.clientCapabilitiesResults;
    }
    
    /**
     * The status command in response to the sending of server capabilities
     */
    private Status serverCapabilitiesStatus = null;
    
    /** 
     * Returns the serverCapabilitiesStatus property.
     *
     * @return the serverCapabilitiesStatus property.
     */
    public Status getServerCapabilitiesStatus() {
        return this.serverCapabilitiesStatus;
    }
    
    /**
     * The client Sync command identifier. It is used when a response is required.
     */
    private CmdID clientSyncCmdId = null;
    
    /** 
     * Returns the clientSyncCmdId property.
     *
     * @return the clientSyncCmdId property.
     */
    public CmdID getClientSyncCmdId() {
        return this.clientSyncCmdId;
    }
    
    /** 
     * Sets the clientSyncCmdId property.
     *
     * @param clientSyncCmdId new value
     */
    public void setClientSyncCmdId(CmdID clientSyncCmdId) {
        this.clientSyncCmdId = clientSyncCmdId;
    }
    
    /**
     * The modification commands the server wants to sent to the client.
     */
    private AbstractCommand[] serverModifications = null;
    
    /** 
     * Returns the serverModifications property.
     *
     * @return the serverModifications property.
     */
    public AbstractCommand[] getServerModifications() {
        return this.serverModifications;
    }
    
    /** 
     * Sets the serverModifications property.
     *
     * @param serverModifications new value
     */
    public void setServerModifications(AbstractCommand[] serverModifications) {
        this.serverModifications = serverModifications;
    }
    
    /**
     * The status to be returned for the client sync command.
     */
    private Status[] clientModificationsStatus = null;
    
    /** 
     * Returns the clientModificationsStatus property.
     *
     * @return the clientModificationsStatus property.
     */
    public Status[] getClientModificationsStatus() {
        return this.clientModificationsStatus;
    }
    
    /** 
     * Sets the clientModificationsStatus property.
     *
     * @param clientModificationsStatus new value
     */
    public void setClientModificationsStatus(Status[] clientModificationsStatus) {
        this.clientModificationsStatus = clientModificationsStatus;
    }
    
    /**
     * Caches the commands sent by the client. It is set during the
     * checking of the requirements.
     */
    private AbstractCommand[] clientCommands = null;

    /** 
     * Returns the clientCommands property.
     *
     * @return the clientCommands property.
     */
    public AbstractCommand[] getClientCommands() {
        return clientCommands;
    }
        
    /**
     * Caches the SyncCommand sent by the client. It is set during the checking
     * of requirements.
     */
    private Sync[] clientSyncCommands = null;
    
    /** 
     * Returns the clientSyncCommands property.
     *
     * @return the clientSyncCommands property.
     */
    public Sync[] getClientSyncCommands() {
        return this.clientSyncCommands;
    }
   
    /**
     * Databases that the server wants to synchronize. 
     */
    private Database[] databases = null;

    /** 
     * Sets the databases property.
     *
     * @param databases new value
     */
    public void setDatabases(Database[] databases) {
        this.databases = databases;
    }

    /** 
     * Returns the databases property.
     *
     * @return the databases property.
     */
    public Database[] getDatabases() {
        return this.databases;
    }
    
    // ---------------------------------------------------------- Public methods
    
    /** Checks that all requirements regarding the header of the initialization
     * packet are respected.
     * @throws ProtocolException if header requirements are not respected
     */
    public void checkHeaderRequirements() throws ProtocolException {
        ClientModificationsRequirements.checkDTDVersion     (syncHeader.getVerDTD()   );
        ClientModificationsRequirements.checkProtocolVersion(syncHeader.getVerProto() );
        ClientModificationsRequirements.checkSessionId      (syncHeader.getSessionID());
        ClientModificationsRequirements.checkMessageId      (syncHeader.getMsgID()    );
        ClientModificationsRequirements.checkTarget         (syncHeader.getTarget()               );
        ClientModificationsRequirements.checkSource         (syncHeader.getSource()               );
    }
    
    /** Checks that all requirements regarding the body of the initialization
     * packet are respected.
     *
     * NOTE: bullet 2 pag 34 is not clear. Ignored for now.
     * @throws ProtocolException if body requirements are not respected
     */
    public void checkBodyRequirements() throws ProtocolException {
        // NOTE: initializes the clientCommands property        
        clientCommands = (AbstractCommand[])syncBody.getCommands().toArray(new AbstractCommand[0]);
        
        //
        // If the server sent the device information to the client and requested
        // a response, serverCapabilitiesCmdId contains the command id of the
        // request command. A Status command with the same cmd id reference 
        // must exist.
        //
        checkServerCapabilitiesStatus();
        
        //
        // If the server requested the device capabilities of the client, 
        // clientCapabilitiesCmdId contains the command id of the Get command. 
        // A Results command with the same cmd id reference must exist.
        //
        checkClientCapabilitiesResult();

        //
        // The Sync command must exists
        //
        checkSyncCommand();
    }
    
    // ----------------------------------------------------------- getResponse()
    
    /**
     * Constructs a proper response message.<p>
     * The sync package to the client has the following purposes:
     * <ul>
     *  <li>To inform the client about the results of sync analysis.
     *  <li>To inform about all data modifications, which have happened in the 
     *      server since the previous time when the server has sent the 
     *      modifications to the client.
     * </ul>
     *
     * @return the response message
     *
     * @throws ProtocolException in case of error or inconsistency
     */
    public SyncML getResponse() throws ProtocolException {
        ArrayList commandList = new ArrayList();
        
        if (idGenerator == null) {
            throw new NullPointerException("The id generator is null. Please set a value for idGenerator");
        }
        
        //
        // Constructs all required response commands.
        //
        // NOTE: if NoResp is specified in the header element, than no 
        //       response commands must be returned regardless NoResp is 
        //       specified or not in subsequent commands
        //
        if (syncHeader.isNoResp() == false) {

            TargetRef[] targetRefs = new TargetRef[] { new TargetRef(syncHeader.getTarget().getLocURI()) };
            SourceRef[] sourceRefs = new SourceRef[] { new SourceRef(syncHeader.getSource().getLocURI()) };