1 <?php
2 /*
3 Copyright (c) 2012, University of Cambridge Computing Service
4
5 This file is part of the Lookup/Ibis client library.
6
7 This library is free software: you can redistribute it and/or modify
8 it under the terms of the GNU Lesser General Public License as published
9 by the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
15 License for more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with this library. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21 require_once "IbisContactRow.php";
22 require_once "IbisDto.php";
23 require_once "IbisGroup.php";
24 require_once "IbisPerson.php";
25
26 /**
27 * Class representing an institution returned by the web service API.
28 *
29 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
30 */
31 class IbisInstitution extends IbisDto
32 {
33 /* Properties marked as @XmlAttribte in the JAXB class */
34 protected static $xmlAttrs = array("cancelled", "instid", "id", "ref");
35
36 /* Properties marked as @XmlElement in the JAXB class */
37 protected static $xmlElems = array("name", "acronym");
38
39 /* Properties marked as @XmlElementWrapper in the JAXB class */
40 protected static $xmlArrays = array("attributes", "contactRows", "members",
41 "parentInsts", "childInsts", "groups",
42 "membersGroups", "managedByGroups");
43
44 /** @var boolean Flag indicating if the institution is cancelled. */
45 public $cancelled;
46
47 /** @var string The institution's unique ID (e.g., "CS"). */
48 public $instid;
49
50 /** @var string The institution's name. */
51 public $name;
52
53 /** @var string The institution's acronym, if set (e.g., "UCS"). */
54 public $acronym;
55
56 /**
57 * @var IbisAttribute[] A list of the institution's attributes. This will
58 * only be populated if the ``fetch`` parameter includes the
59 * ``"all_attrs"`` option, or any specific attribute schemes such as
60 * ``"email"`` or ``"address"``, or the special pseudo-attribute scheme
61 * ``"phone_numbers"``.
62 */
63 public $attributes;
64
65 /**
66 * @var IbisContactRow[] A list of the institution's contact rows. This
67 * will only be populated if the ``fetch`` parameter includes the
68 * ``"contact_rows"`` option.
69 */
70 public $contactRows;
71
72 /**
73 * @var IbisPerson[] A list of the institution's members. This will only
74 * be populated if the ``fetch`` parameter includes the ``"all_members"``
75 * option.
76 */
77 public $members;
78
79 /**
80 * @var IbisInstitution[] A list of the institution's parent
81 * institutions. This will only be populated if the ``fetch`` parameter
82 * includes the ``"parent_insts"`` option.
83 *
84 * NOTE: Currently all institutions have one parent, but in the future
85 * institutions may have multiple parents.
86 */
87 public $parentInsts;
88
89 /**
90 * @var IbisInstitution[] A list of the institution's child institutions.
91 * This will only be populated if the ``fetch`` parameter includes the
92 * ``"child_insts"`` option.
93 */
94 public $childInsts;
95
96 /**
97 * @var IbisGroup[] A list of all the groups that belong to the
98 * institution. This will only be populated if the ``fetch`` parameter
99 * includes the ``"inst_groups"`` option.
100 */
101 public $groups;
102
103 /**
104 * @var IbisGroup[] A list of the groups that form the institution's
105 * membership. This will only be populated if the ``fetch`` parameter
106 * includes the ``"members_groups"`` option.
107 */
108 public $membersGroups;
109
110 /**
111 * @var IbisGroup[] A list of the groups that manage this institution.
112 * This will only be populated if the ``fetch`` parameter includes the
113 * ``"managed_by_groups"`` option.
114 */
115 public $managedByGroups;
116
117 /**
118 * @ignore
119 * @var string An ID that can uniquely identify this institution within
120 * the returned XML/JSON document. This is only used in the flattened
121 * XML/JSON representation (if the "flatten" parameter is specified).
122 */
123 public $id;
124
125 /**
126 * @ignore
127 * @var string A reference (by id) to an institution element in the
128 * XML/JSON document. This is only used in the flattened XML/JSON
129 * representation (if the "flatten" parameter is specified).
130 */
131 public $ref;
132
133 /* Flag to prevent infinite recursion due to circular references. */
134 private $unflattened;
135
136 /**
137 * @ignore
138 * Create an IbisInstitution from the attributes of an XML node.
139 *
140 * @param array $attrs The attributes on the XML node.
141 */
142 public function __construct($attrs=array())
143 {
144 parent::__construct($attrs);
145 if (isset($this->cancelled))
146 $this->cancelled = strcasecmp($this->cancelled, "true") == 0;
147 $this->unflattened = false;
148 }
149
150 /**
151 * @ignore
152 * Unflatten a single IbisInstitution.
153 *
154 * @param IbisResultEntityMap $em The mapping from IDs to entities.
155 */
156 public function unflatten($em)
157 {
158 if (isset($this->ref))
159 {
160 $inst = $em->getInstitution($this->ref);
161 if (!$inst->unflattened)
162 {
163 $inst->unflattened = true;
164 IbisContactRow::unflattenContactRows($em, $inst->contactRows);
165 IbisPerson::unflattenPeople($em, $inst->members);
166 IbisInstitution::unflattenInsts($em, $inst->parentInsts);
167 IbisInstitution::unflattenInsts($em, $inst->childInsts);
168 IbisGroup::unflattenGroups($em, $inst->groups);
169 IbisGroup::unflattenGroups($em, $inst->membersGroups);
170 IbisGroup::unflattenGroups($em, $inst->managedByGroups);
171 }
172 return $inst;
173 }
174 return $this;
175 }
176
177 /**
178 * @ignore
179 * Unflatten a list of IbisInstitution objects (done in place).
180 *
181 * @param IbisResultEntityMap $em The mapping from IDs to entities.
182 * @param IbisInstitution[] $insts The institutions to unflatten.
183 */
184 public static function unflattenInsts($em, &$insts)
185 {
186 if (isset($insts))
187 foreach ($insts as $idx => $inst)
188 $insts[$idx] = $inst->unflatten($em);
189 }
190 }
191