HelpSource/Reference/asTarget.schelp

   1 title:: asTarget
   2 summary:: Convert to a valid Node Target
   3 categories:: Server>Nodes
   4 related:: Classes/Node
   5
   6 method:: asTarget
   7
   8 The classes listed below implement the method code::asTarget::. This is used widely in the link::Classes/Node:: classes ( link::Classes/Group:: and link::Classes/Synth:: ) to convert non-Node objects to an appropriate target.
   9 This allows nil and instances of link::Classes/Server:: to be used as targets. This can be useful when writing classes which create nodes internally, but in most cases there should be little need to call asTarget in normal use.
  10
  11 For an updated list of which classes that implements code::asTarget::, see asTarget in link::Overviews/Methods#asTarget::
  12
  13 definitionlist::
  14 ## link::Classes/Node#-asTarget:: || Returns the instance of Node itself. The subclasses of Node (Synth and Group) are valid targets and require no conversion.
  15
  16 ## link::Classes/Server#-asTarget:: || Returns a link::Classes/Group:: object representing the link::Reference/default_group:: of this instance of Server. Note that this object may not be identical with other objects representing the default group, but will be equivalent.
  17 code::
  18 s = Server.default;
  19 g = s.asTarget;     // the default group of s
  20 h = s.defaultGroup; // and again
  21 g == h;             // true
  22 g === h;            // false
  23 ::
  24
  25 ## link::Classes/Nil#-asTarget:: || Returns a link::Classes/Group:: object representing the link::Reference/default_group:: of the current default link::Classes/Server::.
  26 code::
  27 s = Server.default;
  28 g = nil.asTarget;
  29 g == s.defaultGroup; // true
  30 ::
  31
  32 ## link::Classes/Integer#-asTarget:: || Returns a link::Classes/Group:: object representing a group node on the current default Server with this Integer as its node ID number.
  33 Note:: Although this can be convenient in some cases, it does not create the corresponding node on the default server, nor does it check to make sure that it exists. As well it does not directly access the server's NodeIDAllocator, so duplication of node IDs is possible. For these reasons this method should be used with care. When not dealing with the default Server, Group-basicNew is safer and simpler, as otherwise one needs to set the server instance variable to ensure correct targeting.
  34 code::
  35 /////// Showing the problems
  36
  37 s = Server.default;
  38 s.boot;
  39 g = s.nextNodeID.asTarget;
  40 x = Synth.head(g, "default");   // but g doesn't exist on the server
  41 s.sendMsg(*g.addToHeadMsg);     // now it's sent to the default server, in the default group
  42 x = Synth.head(g, "default");   // now this works
  43 x.free; g.free;
  44
  45 // if not using the default Server Integer-asTarget can be problematic
  46
  47 Server.default = Server.local;
  48 Server.default.boot;            // quit the default server
  49 i = Server.internal; i.boot;
  50 g = i.nextNodeID.asTarget;
  51 i.sendMsg(*g.addToHeadMsg);     // seems to work, but...
  52 x = Synth.head(g, "default");   // oops, this goes to the default server, so Group not Found
  53 g.server == Server.default;     // true, so that's the problem
  54 g.server = i;
  55 x = Synth.head(g, "default");   // now to the right place
  56 x.free; g.free;
  57 ::
  58 code::
  59 /////// A more practical example
  60
  61 s = Server.default;
  62 s.boot;
  63 s.sendMsg(\g_new, x = s.nextNodeID);
  64 // ...
  65
  66 // now if we need to use Node objects for some reason
  67 y = Synth.head(x.asTarget, "default");
  68
  69 // this is simpler than Group.basicNew(s, x);, providing you're using the default server:
  70 z = Synth.head(Group.basicNew(s, x), "default");
  71
  72 y.free; z.free; x.asTarget.free;
  73 ::
  74 ::
  75