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
23 /**
24 * Class representing an attribute of a person or institution returned by
25 * the web service API. Note that for institution attributes, the
26 * {@link instid}, {@link visibility} and {@link owningGroupid} fields will
27 * be ``null``.
28 *
29 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
30 */
31 class IbisAttribute extends IbisDto
32 {
33 /* Properties marked as @XmlAttribte in the JAXB class */
34 protected static $xmlAttrs = array("attrid", "scheme", "instid",
35 "visibility", "effectiveFrom",
36 "effectiveTo", "owningGroupid");
37
38 /* Properties marked as @XmlElement in the JAXB class */
39 protected static $xmlElems = array("value", "binaryData", "comment");
40
41 /** @var int The unique internal identifier of the attribute. */
42 public $attrid;
43
44 /** @var string The attribute's scheme. */
45 public $scheme;
46
47 /** @var string The attribute's value (except for binary attributes). */
48 public $value;
49
50 /**
51 * @var string The binary data held in the attribute (e.g., a JPEG
52 * photo).
53 */
54 public $binaryData;
55
56 /** @var string Any comment associated with the attribute. */
57 public $comment;
58
59 /**
60 * @var string For a person attribute, the optional institution that the
61 * attribute is associated with. This will not be set for institution
62 * attributes.
63 */
64 public $instid;
65
66 /**
67 * @var string For a person attribute, it's visibility (``"private"``,
68 * ``"institution"``, ``"university"`` or ``"world"``). This
69 * will not be set for institution attributes.
70 */
71 public $visibility;
72
73 /**
74 * @var DateTime For time-limited attributes, the date from which it
75 * takes effect.
76 */
77 public $effectiveFrom;
78
79 /**
80 * @var DateTime For time-limited attributes, the date after which it is
81 * no longer effective.
82 */
83 public $effectiveTo;
84
85 /**
86 * @var string For a person attribute, the ID of the group that owns it
87 * (typically the user agent group that created it).
88 */
89 public $owningGroupid;
90
91 /**
92 * @ignore
93 * Create an IbisAttribute from the attributes of an XML node.
94 *
95 * @param array $attrs The attributes on the XML node.
96 */
97 public function __construct($attrs=array())
98 {
99 parent::__construct($attrs);
100 if (isset($this->attrid))
101 $this->attrid = (int )$this->attrid;
102 if (isset($this->effectiveFrom))
103 $this->effectiveFrom = new DateTime($this->effectiveFrom);
104 if (isset($this->effectiveTo))
105 $this->effectiveTo = new DateTime($this->effectiveTo);
106 }
107
108 /**
109 * @ignore
110 * Overridden end element callback to decode binary data.
111 *
112 * @param string $tagname The name of the XML element.
113 * @param string $data The textual value of the XML element.
114 * @return void.
115 */
116 public function endChildElement($tagname, $data)
117 {
118 parent::endChildElement($tagname, $data);
119 if ($tagname === "binaryData" && isset($this->binaryData))
120 $this->binaryData = base64_decode($this->binaryData);
121 }
122
123 /**
124 * Encode this attribute as an ASCII string suitable for passing as a
125 * parameter to a web service API method. This string is compatible with
126 * ``valueOf(java.lang.String)`` on the corresponding Java class,
127 * used on the server to decode the attribute parameter.
128 *
129 * NOTE: This requires that the attribute's {@link scheme} field be
130 * set, and typically the {@link value} or {@link binaryData} should
131 * also be set.
132 *
133 * @return string The string encoding of this attribute.
134 */
135 public function encodedString()
136 {
137 if (is_null($this->scheme))
138 throw new Exception("Attribute scheme must be set");
139
140 $result = "scheme:" . base64_encode($this->scheme);
141 if (isset($this->attrid))
142 $result .= ",attrid:" . $this->attrid;
143 if (isset($this->value))
144 $result .= ",value:" . base64_encode($this->value);
145 if (isset($this->binaryData))
146 $result .= ",binaryData:" . base64_encode($this->binaryData);
147 if (isset($this->comment))
148 $result .= ",comment:" . base64_encode($this->comment);
149 if (isset($this->instid))
150 $result .= ",instid:" . base64_encode($this->instid);
151 if (isset($this->visibility))
152 $result .= ",visibility:" . base64_encode($this->visibility);
153 if (isset($this->effectiveFrom))
154 $result .= ",effectiveFrom:" . $this->effectiveFrom->format("d M Y");
155 if (isset($this->effectiveTo))
156 $result .= ",effectiveTo:" . $this->effectiveTo->format("d M Y");
157 if (isset($this->owningGroupid))
158 $result .= ",owningGroupid:" . base64_encode($this->owningGroupid);
159 return $result;
160 }
161 }
162