// sod.idl -- Projeto de Sistemas de Objetos Distribuídos 
//            Definições de Interfaces

module SOD {

    // Um atributo (Attr) é um par nome, valor
    struct Attr {
        string name;
        string value;
    };

    // Uma AttrList é uma lista de atributos
    typedef sequence<Attr> AttrList;

    // Exceção lançada pela operação que adiciona um Attr a um Record
    exception IsKey {
        Attr keyAttr;
    };

    // Exceção lançada pela operação que adiciona um Record a um RecordSet
    exception AlreadyExists {
        Attr keyAttr;
    };

    // Exceção lançada pela operação que busca um Record pela chave
    exception NotFound {
        Attr keyAttr;
    };

    // Um Record (registro) é um objeto ao qual você pode adicionar atributos.
    // O Record pode ter vários atributos com o mesmo nome. Um dos seus
    // atributos é o atributo chave do registro. Nenhum outro atributo pode 
    // ter nome igual ao do atributo chave (mesmo que tenha valor diferente).
    //
    interface Record {

        // Adiciona o atributo attr a este Record. Lança IsKey se o campo 
        // name de attr for igual ao campo name da chave do registro.
        void add(in Attr attr) raises(IsKey);

        // Retorna a lista de atributos deste Record
        AttrList list();

    };
    
    // Uma RecordList é uma lista de registros
    typedef sequence<Record> RecordList;

    // Um RecordIterador é um objeto auxiliar, transiente, que um cliente usa
    // para iterar sobre uma seqüência de registros. É inteiramente análogo a 
    // um BindingIterator do CosNaming.
    //
    interface RecordIterator {
        boolean next_one(out Record record);
        boolean next_n(in unsigned long howMany,
                       out RecordList recordList);
        void destroy();
    };

    // Um RecordSet é um conjunto de registros
    //
    interface RecordSet {

        // Cria um novo registro e o adiciona a este RecordSet. 
        // O Record recém-criado tem só um atributo, dado pelo parâmetro
        // keyAttr, que fica sendo a chave do novo registro. 
        // Lança AlreadyExists caso já exista algum registro com essa chave, 
        // ou seja, se neste RecordSet já houver um registro cuja chave tenha
        // campos name e value iguais aos do parâmetro keyAttr.
        Record addRecord(in Attr keyAttr) raises(AlreadyExists);

        // Busca um registro pela chave. Lança NotFound se neste RecordSet não
        // houver nenhum com chave keyAttr.
        Record getByKey(in Attr keyAttr) raises(NotFound);

        // Retorna o conjunto de registros deste RecordSet. O valor de retorno
        // da operação é uma lista com até howMany registros. Caso o RecordSet
        // tenha mais que howMany registros, esta operação retorna em it um 
        // iterador para os demais registros.
        RecordList getAll(in unsigned long howMany, out RecordIterator it);


        // Retorna um subconjunto dos registros deste RecordSet. Se o 
        // parâmetro oneIsSufficient for true, é retornado o conjunto dos   
        // registros que contém algum dos atributos listados no parâmetro
        // contained. Se o parâmetro oneIsSufficient for false, é retornado o
        // conjunto dos registros que contém todos os atributos listados no
        // parâmetro contained. Em qualquer dos casos, consideramos que um
        // registro contém um atributo attr se o registro tiver algum atributo
        // cujo campo name é igual ao campo name de attr e cujo campo value 
        // contém (como substring) o campo value de attr. 
        // O valor de retorno desta operação é uma lista com até howMany
        // registros. Caso o subconjunto a ser retornado tenha mais que
        // howMany registros, a operação retorna em it um iterador para os 
        // demais registros do subconjunto.
        RecordList get(in AttrList contained, in boolean oneIsSufficient,
                       in unsigned long howMany, out RecordIterator it);
    };

    // Interface do "objeto principal" de um servidor
    //
    interface Server {

        // RecordSet local, formado pelos registros residentes neste servidor
        readonly attribute RecordSet localRecordSet;

        // RecordSet global, formado pela união dos RecordSets residentes nos
        // vários servidores. 
        readonly attribute RecordSet globalRecordSet;
    };
};