/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) 2007 University of Washington

 * Authors:  Tom Henderson, Craig Dowell

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * 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

 */

#include "ns3/log.h"

#include "ns3/object.h"

#include "ns3/component-manager.h"

using namespace ns3;

//

// This sample file shows examples of how to use QueryInterface.

//

// QueryInterface is a templated method of class Object, defined in 

// src/core/object.h.  ns-3 objects that derive from class Object

// can have QueryInterface invoked on them.

//

// QueryInterface is a type-safe way to ask an object, at run-time, 

// "Do you support the interface identified by the given InterfaceId?"  

// It avoids deprecated techniques of having to downcast pointers to 

// an object to ask questions about its type.  One or more interfaces

// may be associated with a given object.

// 

// QueryInterface is of most use when working with base class

// pointers of objects that may be subclassed.  For instance,

// one may have a pointer to a Node, but not know whether it has

// an IPv4 stack.  Another example might be to determine whether

// a Node has an EnergyModel, to which calls to decrement energy

// from the node's battery might be made.

//

//

// Object is the base class for ns-3 node-related objects used at 

// the public API.  Object provides reference counting implementations

// and the QueryInterface.

// 

// A common design paradigm for an ns-3 node object, such as a Queue,

// is that we provide an abstract base class that inherits from

// Object.  This class is assigned an interface ID (iid) and 

// contains the basic API for objects in this class and subclasses.

// This base class is specialized to provide implementations of

// the object in question (such as a DropTailQueue).

// 

// The design pattern commonly used is known as the "non-virtual

// public interface" pattern, whereby the public API for this

// object is a set of public non-virtual functions that forward

// to private virtual functions.  The forwarding functions can

// impose pre- and post-conditions on the forwarding call at

// the base class level.

// 

// We'll call this base class "AnInterface" in the example below.

//

// 

class AnInterface : public Object

{

public:

  static const InterfaceId iid;

  void methodA (void);

private:

  virtual void domethodA (void) = 0;

};

void

AnInterface::methodA (void)

{

  NS_LOG_FUNCTION;

  // pre-dispatch asserts

  NS_LOG_LOGIC ("pre-condition");

  domethodA ();

  NS_LOG_LOGIC ("post-condition");

  // post-dispatch asserts

}

//

// The below assignment assigns the InterfaceId of the class AnInterface,

// and declares that the parent iid is that of class Object.

//

const InterfaceId AnInterface::iid = MakeInterfaceId ("AnInterface", Object::iid);

//

// AnImplementation is an implementation of the abstract base class

// defined above. It provides implementation for the virtual functions 

// in the base class.  It defines one ClassId for each constructor, 

// and can also provide an interface itself (in this example, 

// a methodImpl is available)

// 

class AnImplementation : public AnInterface

{

public:

  static const InterfaceId iid;

  static const ClassId cid;

  AnImplementation ();

  void methodImpl (void);

private:

  virtual void domethodA (void);

};

void

AnImplementation::methodImpl (void)

{

  NS_LOG_FUNCTION;

}

AnImplementation::AnImplementation (void)

{

  NS_LOG_FUNCTION;

  // enable our interface

  SetInterfaceId (AnImplementation::iid);

}

void

AnImplementation::domethodA () 

{

  NS_LOG_FUNCTION;

}

//

// The below assignment assigns the InterfaceId of the class AnImplementation,

// and declares that the parent iid is that of class Object.

//

const InterfaceId AnImplementation::iid = 

  MakeInterfaceId ("AnImplementation", AnInterface::iid);

//

// The next few lines are used by the component manager.  They

// state that the component manager can create a new object 

// AnImplementation and return an interface corresponding to 

// the AnImplementation iid.

//

const ClassId AnImplementation::cid = 

  MakeClassId<AnImplementation> 

  ("AnImplementation", AnImplementation::iid);

//

// Extending interfaces

// ==================

// What if AnInterface doesn't provide enough API for your

// object type?

// - if you aren't concerned about backward compatibility and

//   don't mind recompiling, you just add new methods to AnInterface

//   and recompile.

// - if you want to address backward compatibiliy, or allow part

//   of the system to use the old interface, you have to do more.

//   You have to declare a new interface with the new functionality.

//

class AnExtendedInterface : public AnInterface

{

public:

  static const InterfaceId iid;

  void methodB (void);

private:

  virtual void domethodB (void) = 0;

};

const InterfaceId AnExtendedInterface::iid = 

  MakeInterfaceId ("AnExtendedInterface", AnInterface::iid);

//

// Then you need provide an implementation for the virtual 

// methods.  If you are providing a new implementation for 

// everything, the answer is straightforward

//

class ANewImplementation : public AnExtendedInterface

{

public:

  static const InterfaceId iid;

  static const ClassId cid;

  ANewImplementation ();

  void methodImpl (void);

private:

  virtual void domethodA (void) { /* new-implementation-behavior ();  */}

  virtual void domethodB (void) { /* new-implementation-behavior (); */}

};

ANewImplementation::ANewImplementation (void)

{

  // enable our interface

  SetInterfaceId (ANewImplementation::iid);

}

void

ANewImplementation::methodImpl (void)

{

  NS_LOG_FUNCTION;

}

const InterfaceId ANewImplementation::iid = 

  MakeInterfaceId ("ANewImplementation", AnExtendedInterface::iid);

//

// If you want to extend an existing implementation, you can use 

// the existing class to instantiate an implementation of its 

// methods (hasa) and do the following if you can use stuff from 

// the existing class.

//

class AnExtendedImplementation : public AnExtendedInterface

{

public:

  static const InterfaceId iid;

  static const ClassId cid;

  AnExtendedImplementation ();

  void methodImpl (void) { /* pImpl->methodImpl (); */ }

  void methodExtendedImpl (void);

private:

  virtual void domethodA (void) { /* new-implementation-behavior (); */}

  virtual void domethodB (void) { /* new-implementation-behavior (); */}

  Ptr<AnImplementation> pImpl;

};

AnExtendedImplementation::AnExtendedImplementation (void)

{

  pImpl = Create<AnImplementation> (); 

  SetInterfaceId (AnExtendedImplementation::iid);

}

void

AnExtendedImplementation::methodExtendedImpl (void)

{

  NS_LOG_FUNCTION;

}

const InterfaceId AnExtendedImplementation::iid = 

  MakeInterfaceId ("AnExtendedImplementation", AnExtendedInterface::iid);

//

// Inheriting from an existing implementation (isa) and an extended

// interface is tricky, because of the diamond multiple inheritance

// problem.  If the pImpl method above is not desirable, it may

// be that the implementation extension could be aggregated.

// 

// The extension will not have access to the base implementation,

// so this design pattern may be more appropriate if the extension

// is very modular (e.g., add an EnergyModel to a wireless interface)

//

// EXAMPLE NOT YET PROVIDED

int main (int argc, char *argv[])

{

  Ptr<AnInterface> aBase = ComponentManager::Create<AnImplementation> 

    (AnImplementation::cid, AnInterface::iid);

  NS_ASSERT (aBase != 0);

  aBase->methodA ();

  //aBase->methodImpl (); // XXX won't compile, aBase not right ptr type

  Ptr<AnImplementation> aBaseImplPtr = 

    aBase-> QueryInterface<AnImplementation> (AnImplementation::iid);

  aBaseImplPtr->methodImpl ();

  aBaseImplPtr->methodA();

  // Test symmetric property of QueryInterface 

  Ptr<AnInterface> aBase2 = 

    aBaseImplPtr-> QueryInterface<AnInterface> (AnInterface::iid);

  aBase2->methodA ();

  return 0;

}