| Index: trunk/extensions/SemanticMediaWiki/includes/dataitems/SMW_DI_Container.php |
| — | — | @@ -5,24 +5,29 @@ |
| 6 | 6 | */ |
| 7 | 7 | |
| 8 | 8 | /** |
| 9 | | - * Subclass of SMWSemanticData that can be made read only to enforce the |
| 10 | | - * immutability of all SMW data items. This ensures that the container dataitem |
| 11 | | - * can safely give out an object reference without concern that this is |
| 12 | | - * exploited to indirectly change its content. |
| | 9 | + * Subclass of SMWSemanticData that is used to store the data in SMWDIContainer |
| | 10 | + * objects. It is special since the subject that the stored property-value pairs |
| | 11 | + * refer to is not specified explicitly. Instead, the subject used in container |
| | 12 | + * data items is determined by the stored data together with the page that the |
| | 13 | + * data item is assigned to (the "master page" of this data). Maintaining the |
| | 14 | + * relation to the master page is important for data management since the |
| | 15 | + * subjects of container data items must be deleted when deleting the value. |
| 13 | 16 | * |
| 14 | | - * Objects of this class are usually only made immutable when passed to a data |
| 15 | | - * item, so they can be built as usual. When cloning the object, the clone |
| 16 | | - * becomes mutable again. This is safe since all data is stored in arrays that |
| 17 | | - * contain only immutable objects and values of basic types. Arrays are copied |
| 18 | | - * (lazily) when cloning in PHP, so later changes in the cloce will not affect |
| 19 | | - * the original. |
| | 17 | + * Therefore, this container data provides a method setMasterPage() that is used |
| | 18 | + * to define the master page. SMWSemanticData will always call this method when |
| | 19 | + * it is given a container data item to store. Until this is done, the subject |
| | 20 | + * of the container is "anonymous" -- it has no usable name. This can be tested |
| | 21 | + * with hasAnonymousSubject(). When trying to access the subject in this state, |
| | 22 | + * an Exception will be thrown. Note that container data items that are not |
| | 23 | + * related to any master page are necessary, e.g. when specifying such a value |
| | 24 | + * in a search form where the master page is not known. |
| 20 | 25 | * |
| 21 | | - * In contrast to normal SMWSemanticData objects, SMWContainerSemanticData can |
| 22 | | - * be created without specifying a subject. In this case, the subject is some |
| 23 | | - * "anonymous" object that is left unspecified (for search) or generated later |
| 24 | | - * (for storage). The method hasAnonymousSubject() should be used to check for |
| 25 | | - * this case (as the method getSubject() will always return a valid subject). |
| 26 | | - * See the documentation of SMWDIContainer for further details. |
| | 26 | + * See also the documentation of SMWDIContainer. |
| | 27 | + * |
| | 28 | + * @since 1.6 |
| | 29 | + * |
| | 30 | + * @author Markus Krötzsch |
| | 31 | + * @ingroup SMWDataItems |
| 27 | 32 | */ |
| 28 | 33 | class SMWContainerSemanticData extends SMWSemanticData { |
| 29 | 34 | |
| — | — | @@ -130,26 +135,28 @@ |
| 131 | 136 | * This class implements container data items that can store SMWSemanticData |
| 132 | 137 | * objects. Containers are not dataitems in the proper sense: they do not |
| 133 | 138 | * represent a single, opaque value that can be assigned to a property. Rather, |
| 134 | | - * a container represents a collection of individual property-value assignments. |
| 135 | | - * When a container is stored, these individual data assignments are stored -- |
| 136 | | - * the data managed by SMW never contains any "container", just individual |
| 137 | | - * property assignments. Likewise, when a container is used in search, it is |
| 138 | | - * interpreted as a patterns of possible property assignments, and this pattern |
| 139 | | - * is searched for. |
| | 139 | + * a container represents a "subobject" with a number of property-value |
| | 140 | + * assignments. When a container is stored, these individual data assignments |
| | 141 | + * are stored -- the data managed by SMW never contains any "container", just |
| | 142 | + * individual property assignments for the subobject. Likewise, when a container |
| | 143 | + * is used in search, it is interpreted as a patterns of possible property |
| | 144 | + * assignments, and this pattern is searched for. |
| 140 | 145 | * |
| 141 | 146 | * The data encapsulated in a container data item is essentially an |
| 142 | | - * SMWSemanticData object. The data represented by the container consists of |
| 143 | | - * the data stored in this SMWSemanticData object. As a special case, it is |
| 144 | | - * possible that the subject of this data is left unspecified. The name of the |
| 145 | | - * subject in this case is not part of the data: when storing such containers, a |
| 146 | | - * new name will be invented; when searching for such containers, only the |
| 147 | | - * property-value pairs are considered relevant in the search. If the subject is |
| 148 | | - * given (i.e. not anonymous), and the container DI is used as a property value |
| 149 | | - * for a wikipage Foo, then the subject of the container must be a subobject of |
| 150 | | - * Foo, for example Foo#section. In this case "Foo" is called the master page of |
| 151 | | - * the container. To get a suitable subject for a given master page, the method |
| 152 | | - * getSubjectPage() can be used. |
| | 147 | + * SMWSemanticData object of class SMWContainerSemanticData. This class has a |
| | 148 | + * special handling for the subject of the stored annotations (i.e. the |
| | 149 | + * subobject). See the repsective documentation for details. |
| | 150 | + * |
| | 151 | + * Being a mere placeholder/template for other data, an SMWDIContainer is not |
| | 152 | + * immutable as the other basic data items. New property-value pairs can always |
| | 153 | + * be added to the internal SMWContainerSemanticData. Moreover, the subobject |
| | 154 | + * that the container refers to is set only after it has been created, when the |
| | 155 | + * data item is added as a property value to some existing SMWSemanticData. |
| | 156 | + * Only after this has happened is the subobject fully defined. Any attempt to |
| | 157 | + * obtain the subobject from the internal SMWContainerSemanticData before it |
| | 158 | + * has been defined will result in an SMWDataItemException. |
| 153 | 159 | * |
| | 160 | + * |
| 154 | 161 | * @since 1.6 |
| 155 | 162 | * |
| 156 | 163 | * @author Markus Krötzsch |