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 "IbisDto.php";
22 require_once "IbisInstitution.php";
23 require_once "IbisPerson.php";
24
25 /**
26 * Class representing a group returned by the web service API.
27 *
28 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
29 */
30 class IbisGroup extends IbisDto
31 {
32 /* Properties marked as @XmlAttribte in the JAXB class */
33 protected static $xmlAttrs = array("cancelled", "groupid", "id", "ref");
34
35 /* Properties marked as @XmlElement in the JAXB class */
36 protected static $xmlElems = array("name", "title", "description",
37 "emails", "membersOfInst");
38
39 /* Properties marked as @XmlElementWrapper in the JAXB class */
40 protected static $xmlArrays = array("members", "directMembers",
41 "owningInsts", "managesInsts",
42 "managesGroups", "managedByGroups",
43 "readsGroups", "readByGroups",
44 "includesGroups", "includedByGroups");
45
46 /** @var boolean Flag indicating if the group is cancelled. */
47 public $cancelled;
48
49 /**
50 * @var string The group's numeric ID (actually a string e.g., "100656").
51 */
52 public $groupid;
53
54 /** @var string The group's unique name (e.g., "cs-editors"). */
55 public $name;
56
57 /** @var string The group's title. */
58 public $title;
59
60 /** @var string The more detailed description of the group. */
61 public $description;
62
63 /** @var string The group's email address. */
64 public $email;
65
66 /**
67 * @var IbisInstitution The details of the institution for which this
68 * group forms all or part of the membership. This will only be set for
69 * groups that are membership groups of institutions if the ``fetch``
70 * parameter includes the ``"members_of_inst"`` option.
71 */
72 public $membersOfInst;
73
74 /**
75 * @var IbisPerson[] A list of the group's members, including
76 * (recursively) any members of any included groups. This will only be
77 * populated if the ``fetch`` parameter includes the ``"all_members"``
78 * option.
79 */
80 public $members;
81
82 /**
83 * @var IbisPerson[] A list of the group's direct members, not including
84 * any members included via groups included by this group. This will only
85 * be populated if the ``fetch`` parameter includes the
86 * ``"direct_members"`` option.
87 */
88 public $directMembers;
89
90 /**
91 * @var IbisInstitution[] A list of the institutions to which this group
92 * belongs. This will only be populated if the ``fetch`` parameter
93 * includes the ``"owning_insts"`` option.
94 */
95 public $owningInsts;
96
97 /**
98 * @var IbisInstitution[] A list of the institutions managed by this
99 * group. This will only be populated if the ``fetch`` parameter includes
100 * the ``"manages_insts"`` option.
101 */
102 public $managesInsts;
103
104 /**
105 * @var IbisGroup[] A list of the groups managed by this group. This will
106 * only be populated if the ``fetch`` parameter includes the
107 * ``"manages_groups"`` option.
108 */
109 public $managesGroups;
110
111 /**
112 * @var IbisGroup[] A list of the groups that manage this group. This
113 * will only be populated if the ``fetch`` parameter includes the
114 * ``"managed_by_groups"`` option.
115 */
116 public $managedByGroups;
117
118 /**
119 * @var IbisGroup[] A list of the groups that this group has privileged
120 * access to. Members of this group will be able to read the members of
121 * any of those groups, regardless of the membership visibilities. This
122 * will only be populated if the ``fetch`` parameter includes the
123 * ``"reads_groups"`` option.
124 */
125 public $readsGroups;
126
127 /**
128 * @var IbisGroup[] A list of the groups that have privileged access to
129 * this group. Members of those groups will be able to read the members
130 * of this group, regardless of the membership visibilities. This will
131 * only be populated if the ``fetch`` parameter includes the
132 * ``"read_by_groups"`` option.
133 */
134 public $readByGroups;
135
136 /**
137 * @var IbisGroup[] A list of the groups directly included in this group.
138 * Any members of the included groups (and recursively any groups that
139 * they include) will automatically be included in this group. This will
140 * only be populated if the ``fetch`` parameter includes the
141 * ``"includes_groups"`` option.
142 */
143 public $includesGroups;
144
145 /**
146 * @var IbisGroup[] A list of the groups that directly include this
147 * group. Any members of this group will automatically be included in
148 * those groups (and recursively in any groups that include those
149 * groups). This will only be populated if the ``fetch`` parameter
150 * includes the ``"included_by_groups"`` option.
151 */
152 public $includedByGroups;
153
154 /**
155 * @ignore
156 * @var string An ID that can uniquely identify this group within the
157 * returned XML/JSON document. This is only used in the flattened
158 * XML/JSON representation (if the ``"flatten"`` parameter is specified).
159 */
160 public $id;
161
162 /**
163 * @ignore
164 * @var string A reference (by id) to a group element in the XML/JSON
165 * document. This is only used in the flattened XML/JSON representation
166 * (if the ``"flatten"`` parameter is specified).
167 */
168 public $ref;
169
170 /* Flag to prevent infinite recursion due to circular references. */
171 private $unflattened;
172
173 /**
174 * @ignore
175 * Create an IbisGroup from the attributes of an XML node.
176 *
177 * @param array $attrs The attributes on the XML node.
178 */
179 public function __construct($attrs=array())
180 {
181 parent::__construct($attrs);
182 if (isset($this->cancelled))
183 $this->cancelled = strcasecmp($this->cancelled, "true") == 0;
184 $this->unflattened = false;
185 }
186
187 /**
188 * @ignore
189 * Unflatten a single IbisGroup.
190 *
191 * @param IbisResultEntityMap $em The mapping from IDs to entities.
192 */
193 public function unflatten($em)
194 {
195 if (isset($this->ref))
196 {
197 $group = $em->getGroup($this->ref);
198 if (!$group->unflattened)
199 {
200 $group->unflattened = true;
201 if (isset($group->membersOfInst))
202 $group->membersOfInst = $group->membersOfInst->unflatten($em);
203 IbisPerson::unflattenPeople($em, $group->members);
204 IbisPerson::unflattenPeople($em, $group->directMembers);
205 IbisInstitution::unflattenInsts($em, $group->owningInsts);
206 IbisInstitution::unflattenInsts($em, $group->managesInsts);
207 IbisGroup::unflattenGroups($em, $group->managesGroups);
208 IbisGroup::unflattenGroups($em, $group->managedByGroups);
209 IbisGroup::unflattenGroups($em, $group->readsGroups);
210 IbisGroup::unflattenGroups($em, $group->readByGroups);
211 IbisGroup::unflattenGroups($em, $group->includesGroups);
212 IbisGroup::unflattenGroups($em, $group->includedByGroups);
213 }
214 return $group;
215 }
216 return $this;
217 }
218
219 /**
220 * @ignore
221 * Unflatten a list of IbisGroup objects (done in place).
222 *
223 * @param IbisResultEntityMap $em The mapping from IDs to entities.
224 * @param IbisGroup[] $groups The groups to unflatten.
225 */
226 public static function unflattenGroups($em, &$groups)
227 {
228 if (isset($groups))
229 foreach ($groups as $idx => $group)
230 $groups[$idx] = $group->unflatten($em);
231 }
232 }
233