Package de.espirit.firstspirit.access.store.sitestore

Interface SiteStoreFolder

All Superinterfaces:
Comparable<StoreElement>, DataProvider, HistoryProvider, IDProvider, StartNode, StoreElement, Workflowable
All Known Subinterfaces:
PageRefFolder, SiteStoreRoot
public interface SiteStoreFolder extends StartNode, DataProvider
Interface providing means to operate on site store folders.
Since:
3.0
Example:
Example how to modify variables of SiteStoreFolder 
import de.espirit.firstspirit.access.store.sitestore.*;

import de.espirit.firstspirit.access.Language;
import de.espirit.firstspirit.access.editor.SiteStoreVariableValue;
import de.espirit.firstspirit.access.editor.value.InvalidValueException;
import de.espirit.firstspirit.access.store.Data;
import de.espirit.firstspirit.access.store.DataValue;
import de.espirit.firstspirit.access.store.ElementDeletedException;
import de.espirit.firstspirit.access.store.LockException;
import de.espirit.firstspirit.forms.FormField;
import de.espirit.firstspirit.forms.NoSuchFormFieldException;


/**
 * Examples how to modify variables of SiteStoreFolder.
 *
 * @since 4.2.34
 */
public class SiteStoreFolderVariablesExample {

	/**
	 * Example how to add a variable.
	 *
	 * @since 4.2.34
	 * @deprecated since 4.2.440 - see {@link #addVariable_FormData(SiteStoreFolder)} instead
	 */
	@Deprecated
	public void addVariable(final SiteStoreFolder folder) throws ClassNotFoundException, IllegalAccessException, InstantiationException, InvalidValueException, LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve Data (variables) from SiteStoreFolder
			final Data data = folder.getData();

			// 3. try to retrieve a DataValue (variable) with desired name
			DataValue dataValue = data.get(variableName);

			// 4. if a DataValue is existent, no new one can created using the desired name
			if (dataValue != null) {
				throw new IllegalArgumentException("Variable named " + variableName + " already existent!");
			}

			// 5. create new DataValue (variable)
			dataValue = data.create(variableName, folder.getProject().getUserService(), null);

			// 6. retrieve the EditorValue from DataValue
			final SiteStoreVariableValue editor = (SiteStoreVariableValue) dataValue.getEditor();

			// 7. set desired value for each language
			for (final Language language : folder.getProject().getLanguages()) {
				editor.set(language, "myValue");
			}

			// 8. don't forget to set changed data back to folder
			folder.setData(data);

			// 9. save changes and unlock the folder
			folder.save("add variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to add a variable.
	 *
	 * @since 4.2.440
	 */
	public void addVariable_FormData(final SiteStoreFolder folder) throws LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve FormData (variables) from SiteStoreFolder
			final SiteStoreVariableFormData formData = folder.getFormData();

			// 3. try to retrieve a DataValue (variable) with desired name
			FormField<String> formField;
			final Language masterLanguage = folder.getProject().getMasterLanguage();
			try {
				formField = formData.get(masterLanguage, variableName);
			} catch (NoSuchFormFieldException e) {
				formField = formData.createVariable(masterLanguage, variableName);
			}

			// 4. set new value
			formField.set("myValue");

			// 5. don't forget to set changed data back to folder
			folder.setFormData(formData);

			// 6. save changes and unlock the folder
			folder.save("add variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to change a variables value.
	 *
	 * @since 4.2.34
	 * @deprecated since 4.2.440 - see {@link #setVariableValue_FormData(SiteStoreFolder)} instead
	 */
	@Deprecated
	public void setVariableValue(final SiteStoreFolder folder) throws InvalidValueException, LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve Data (variables) from SiteStoreFolder
			final Data data = folder.getData();

			// 3. try to retrieve a DataValue (variable) with desired name
			final DataValue dataValue = data.get(variableName);

			// 4. check existence of the DataValue (variable)
			if (dataValue == null) {
				throw new IllegalArgumentException("Variable named " + variableName + " doesn't exist!");
			}

			// 5. retrieve the EditorValue from DataValue
			final SiteStoreVariableValue editor = (SiteStoreVariableValue) dataValue.getEditor();

			// 6. set desired value for each language
			for (final Language language : folder.getProject().getLanguages()) {
				editor.set(language, "myNewValue");
			}

			// 7. don't forget to set changed data back to folder
			folder.setData(data);

			// 8. save changes and unlock the folder
			folder.save("set variable value", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to change a variable value.
	 *
	 * @since 4.2.440
	 */
	public void setVariableValue_FormData(final SiteStoreFolder folder) throws InvalidValueException, LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		// 2. retrieve FormData (variables) from SiteStoreFolder
		final SiteStoreVariableFormData formData = folder.getFormData();

		try {
			// 3. try to retrieve a form field with desired name
			final FormField<String> field = formData.get(folder.getProject().getMasterLanguage(), variableName);

			// 4. set new value
			field.set("myNewValue");

			// 5. don't forget to set changed formdata back to folder
			folder.setFormData(formData);

			// 6. save changes and unlock the folder
			folder.save("set variable value", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to remove a variable.
	 *
	 * @since 4.2.440
	 * @deprecated since 4.2.440 - see {@link #removeVariable_FormData(SiteStoreFolder)} instead
	 */
	@Deprecated
	public void removeVariable(final SiteStoreFolder folder) throws LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve Data (variables) from SiteStoreFolder
			final Data data = folder.getData();

			// 3. try to retrieve a DataValue (variable) with desired name
			final DataValue dataValue = data.get(variableName);

			// 4. check existence of the DataValue (variable)
			if (dataValue == null) {
				throw new IllegalArgumentException("Variable named " + variableName + " doesn't exist!");
			}

			// 5. remove the DataValue
			data.remove(dataValue);

			// 6. don't forget to set changed data back to folder
			folder.setData(data);

			// 7. save changes and unlock the folder
			folder.save("remove variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to remove a variable.
	 *
	 * @since 4.2.34
	 */
	public void removeVariable_FormData(final SiteStoreFolder folder) throws LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve FormData (variables) from SiteStoreFolder
			final SiteStoreVariableFormData formData = folder.getFormData();

			// 3. remove variable with desired name
			formData.removeVariable(variableName);

			// 4. don't forget to set changed formdata back to folder
			folder.setFormData(formData);

			// 5. save changes and unlock the folder
			folder.save("remove variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}
}

  • Field Details

  • Method Details

    • getParentFolder

      @Nullable @Nullable SiteStoreFolder getParentFolder()
      Get the parent folder.
      Returns:
      an instance of SiteStoreRoot or PageRefFolder, or null if the folder is not part of the tree or the root node
      Since:
      3.0

    • isFolder

      boolean isFolder()
      All implementing classes must return true.
      Specified by:
      isFolder in interface StoreElement
      Returns:
      true
      Since:
      3.0

    • getStartNode

      @Nullable @Nullable StartNode getStartNode()
      Returns the startnode of this folder which is a direct child of this folder or null if no start node is defined.
      Returns:
      The defined startnode or null if no start node is defined.
      Since:
      4.0.27
      See Also:

    • setStartNode

      void setStartNode(StartNode startNode)
      Sets the given StartNode as startnode of this sitestore folder.
      Parameters:
      startNode - The node to set as start node.
      Since:
      4.0.27
      See Also:

    • findStartNode

      @Nullable @Nullable StartNode findStartNode()
      Finds recursive the start node in this sub tree. This may return null, e.g. in case this is an empty folder.
      The returned node (if not null) is instance of PageRef and may not be a direct child of this folder.
      Returns:
      A PageRef or null.
      Since:
      4.0.27
      See Also:

    • createPageRefFolder

      PageRefFolder createPageRefFolder(String uid) throws LockException, ElementDeletedException
      Create a new SiteStore-folder in this folder. Short for createPageRefFolder(name, false).
      Parameters:
      uid - uid of the new SiteStore-folder
      Returns:
      SiteStore-folder as an object
      Throws:
      DuplicateReferenceNameException - if an element with the given uid in the same namescope already exists on the server
      LockException - If the folder is locked by another session.
      ElementDeletedException - If the current node has been deleted.
      Since:
      3.0

    • createPageRefFolder

      PageRefFolder createPageRefFolder(String uid, boolean unifyNameOnServer) throws LockException, DuplicateReferenceNameException, ElementDeletedException
      Create a new PageRefFolder as child of this folder.
      Parameters:
      uid - uid of the new PageRefFolder
      unifyNameOnServer - if false a DuplicateReferenceNameException may be thrown, if true the name will be unified on the server if necessary
      Returns:
      SiteStore-folder as an object
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if an element with the given uid in the same namescope already exits on the server
      ElementDeletedException - if this folder is already deleted on the server
      Since:
      4.0

    • createPageRefFolder

      PageRefFolder createPageRefFolder(String uid, Map<Language,String> lang2DisplayName, boolean unifyNameOnServer) throws LockException, DuplicateReferenceNameException, ElementDeletedException
      Create a new PageRefFolder as child of this folder.
      Parameters:
      uid - uid of the new PageRefFolder
      lang2DisplayName - mapping of language to language specific displayname; used to create LanguageInfo nodes
      unifyNameOnServer - if false a DuplicateReferenceNameException may be thrown, if true the name will be unified on the server if necessary
      Returns:
      SiteStore-folder as an object
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if unifyNameOnServer is false and an element with the given uid in the same namescope already exits on the server
      ElementDeletedException - if this folder is already deleted on the server
      Since:
      4.0

    • createPageRefFolder

      @NotNull @NotNull PageRefFolder createPageRefFolder(String uid, Map<Language,String> lang2DisplayName, boolean unifyNameOnServer, IDProvider nextSibling) throws LockException, DuplicateReferenceNameException, ElementDeletedException
      Create a new PageRefFolder as child of this folder and place it before the given next sibling. If no next sibling is given or the given one is no child of this folder, the new child will be appended.
      Parameters:
      uid - The uid of the new PageRefFolder
      lang2DisplayName - The mapping of language to language specific displayname; used to create LanguageInfo nodes
      unifyNameOnServer - if false a DuplicateReferenceNameException may be thrown, if true the name will be unified on the server if necessary
      nextSibling - A sibling to add the new child before in order or null to append the new child.
      Returns:
      SiteStore-folder as an object
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if unifyNameOnServer is false and an element with the given uid in the same namescope already exits on the server
      ElementDeletedException - if this folder is already deleted on the server
      Since:
      5.0.11

    • createPageRef

      PageRef createPageRef(String uid, Page page) throws DuplicateReferenceNameException, LockException, ElementDeletedException
      Create a new page reference entry.
      Parameters:
      uid - uid of the new pageref
      page - page to which the new reference will be linked
      Returns:
      the new created page ref instance
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if there is already an element with the specified uid in the same namescope on the server
      ElementDeletedException - if this folder is already deleted on the server
      Since:
      3.0

    • createPageRef

      PageRef createPageRef(String uid, Page page, boolean unifyNameOnServer) throws LockException, ElementDeletedException
      Creates a new page reference in this folder. The given name is used as suggestion if unifyNameOnServer == true and will be unified on the server if it is necessary.
      Parameters:
      uid - of the new page ref
      page - page to which the new reference will be linked
      unifyNameOnServer - if true the given uid will be unified on server if necessary, otherwise a DuplicateReferenceNameException will be thrown, if a pageref with the given uid already exists on the server
      Returns:
      the new created page ref instance
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if a pageref with the given uid already exists on the server
      ElementDeletedException - if this folder is already deleted on the server
      Since:
      4.0

    • createPageRef

      PageRef createPageRef(String uid, Page page, Map<Language,String> lang2DisplayName, boolean unifyNameOnServer) throws LockException, ElementDeletedException
      Creates a new page reference in this folder.
      The given uid is used as suggestion. If unifyNameOnServer == true the given uid will be unified on server if necessary, otherwise a DuplicateReferenceNameException will be thrown, if a pageref with the given uid already exists on the server.
      Parameters:
      uid - of the new page ref
      page - page to which the new reference will be linked
      lang2DisplayName - mapping of language to language specific displayname; used to create LanguageInfo nodes
      unifyNameOnServer - if true the given uid will be unified on server if necessary, otherwise a DuplicateReferenceNameException will be thrown, if a pageref with the given uid already exists on the server
      Returns:
      the new created page ref instance
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if unifyNameOnServer is false and a pageref with the given uid exists on the server
      ElementDeletedException - if this folder is already deleted on the server
      Since:
      4.2.400

    • createDocumentGroup

      DocumentGroup createDocumentGroup(String uid, boolean unifyNameOnServer) throws LockException, DuplicateReferenceNameException, LicenseException, ElementDeletedException
      Creates a new document group in this folder. The given uid is used as suggestion if unifyNameOnServer == true and will be unified on the server if it is necessary.
      Attention: This functionality is license dependent. To use this method your FIRSTspirit license needs feature 'DOCUMENTGROUP'
      Parameters:
      uid - of the new document group
      unifyNameOnServer - if true the given uid will be unified on server if necessary, otherwise a DuplicateReferenceNameException will be thrown, if an element with the given uid in the same namescope already exists on the server
      Returns:
      the new document group
      Throws:
      LockException - if this folder is locked in another session
      DuplicateReferenceNameException - if unifyNameOnServer == false and an element with the given uid already exists on the server
      LicenseException - if the installed FIRSTspirit license has no feature 'DOCUMENTGROUP'
      ElementDeletedException
      Since:
      4.0.17

    • getFormData

      @NotNull @NotNull SiteStoreVariableFormData getFormData()
      Gets a form data container containing containig all defined sitestore variables. Inherited values are not included.
      Specified by:
      getFormData in interface DataProvider
      Returns:
      the formdata container of this element.
      Since:
      4.2.440
      Example:
      Example how to modify variables of SiteStoreFolder 
      import de.espirit.firstspirit.access.store.sitestore.*;

import de.espirit.firstspirit.access.Language;
import de.espirit.firstspirit.access.editor.SiteStoreVariableValue;
import de.espirit.firstspirit.access.editor.value.InvalidValueException;
import de.espirit.firstspirit.access.store.Data;
import de.espirit.firstspirit.access.store.DataValue;
import de.espirit.firstspirit.access.store.ElementDeletedException;
import de.espirit.firstspirit.access.store.LockException;
import de.espirit.firstspirit.forms.FormField;
import de.espirit.firstspirit.forms.NoSuchFormFieldException;


/**
 * Examples how to modify variables of SiteStoreFolder.
 *
 * @since 4.2.34
 */
public class SiteStoreFolderVariablesExample {

	/**
	 * Example how to add a variable.
	 *
	 * @since 4.2.34
	 * @deprecated since 4.2.440 - see {@link #addVariable_FormData(SiteStoreFolder)} instead
	 */
	@Deprecated
	public void addVariable(final SiteStoreFolder folder) throws ClassNotFoundException, IllegalAccessException, InstantiationException, InvalidValueException, LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve Data (variables) from SiteStoreFolder
			final Data data = folder.getData();

			// 3. try to retrieve a DataValue (variable) with desired name
			DataValue dataValue = data.get(variableName);

			// 4. if a DataValue is existent, no new one can created using the desired name
			if (dataValue != null) {
				throw new IllegalArgumentException("Variable named " + variableName + " already existent!");
			}

			// 5. create new DataValue (variable)
			dataValue = data.create(variableName, folder.getProject().getUserService(), null);

			// 6. retrieve the EditorValue from DataValue
			final SiteStoreVariableValue editor = (SiteStoreVariableValue) dataValue.getEditor();

			// 7. set desired value for each language
			for (final Language language : folder.getProject().getLanguages()) {
				editor.set(language, "myValue");
			}

			// 8. don't forget to set changed data back to folder
			folder.setData(data);

			// 9. save changes and unlock the folder
			folder.save("add variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to add a variable.
	 *
	 * @since 4.2.440
	 */
	public void addVariable_FormData(final SiteStoreFolder folder) throws LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve FormData (variables) from SiteStoreFolder
			final SiteStoreVariableFormData formData = folder.getFormData();

			// 3. try to retrieve a DataValue (variable) with desired name
			FormField<String> formField;
			final Language masterLanguage = folder.getProject().getMasterLanguage();
			try {
				formField = formData.get(masterLanguage, variableName);
			} catch (NoSuchFormFieldException e) {
				formField = formData.createVariable(masterLanguage, variableName);
			}

			// 4. set new value
			formField.set("myValue");

			// 5. don't forget to set changed data back to folder
			folder.setFormData(formData);

			// 6. save changes and unlock the folder
			folder.save("add variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to change a variables value.
	 *
	 * @since 4.2.34
	 * @deprecated since 4.2.440 - see {@link #setVariableValue_FormData(SiteStoreFolder)} instead
	 */
	@Deprecated
	public void setVariableValue(final SiteStoreFolder folder) throws InvalidValueException, LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve Data (variables) from SiteStoreFolder
			final Data data = folder.getData();

			// 3. try to retrieve a DataValue (variable) with desired name
			final DataValue dataValue = data.get(variableName);

			// 4. check existence of the DataValue (variable)
			if (dataValue == null) {
				throw new IllegalArgumentException("Variable named " + variableName + " doesn't exist!");
			}

			// 5. retrieve the EditorValue from DataValue
			final SiteStoreVariableValue editor = (SiteStoreVariableValue) dataValue.getEditor();

			// 6. set desired value for each language
			for (final Language language : folder.getProject().getLanguages()) {
				editor.set(language, "myNewValue");
			}

			// 7. don't forget to set changed data back to folder
			folder.setData(data);

			// 8. save changes and unlock the folder
			folder.save("set variable value", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to change a variable value.
	 *
	 * @since 4.2.440
	 */
	public void setVariableValue_FormData(final SiteStoreFolder folder) throws InvalidValueException, LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		// 2. retrieve FormData (variables) from SiteStoreFolder
		final SiteStoreVariableFormData formData = folder.getFormData();

		try {
			// 3. try to retrieve a form field with desired name
			final FormField<String> field = formData.get(folder.getProject().getMasterLanguage(), variableName);

			// 4. set new value
			field.set("myNewValue");

			// 5. don't forget to set changed formdata back to folder
			folder.setFormData(formData);

			// 6. save changes and unlock the folder
			folder.save("set variable value", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to remove a variable.
	 *
	 * @since 4.2.440
	 * @deprecated since 4.2.440 - see {@link #removeVariable_FormData(SiteStoreFolder)} instead
	 */
	@Deprecated
	public void removeVariable(final SiteStoreFolder folder) throws LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve Data (variables) from SiteStoreFolder
			final Data data = folder.getData();

			// 3. try to retrieve a DataValue (variable) with desired name
			final DataValue dataValue = data.get(variableName);

			// 4. check existence of the DataValue (variable)
			if (dataValue == null) {
				throw new IllegalArgumentException("Variable named " + variableName + " doesn't exist!");
			}

			// 5. remove the DataValue
			data.remove(dataValue);

			// 6. don't forget to set changed data back to folder
			folder.setData(data);

			// 7. save changes and unlock the folder
			folder.save("remove variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}


	/**
	 * Example how to remove a variable.
	 *
	 * @since 4.2.34
	 */
	public void removeVariable_FormData(final SiteStoreFolder folder) throws LockException, ElementDeletedException {

		final String variableName = "myVariable";

		// 1. lock the folder
		folder.setLock(true, false);

		try {
			// 2. retrieve FormData (variables) from SiteStoreFolder
			final SiteStoreVariableFormData formData = folder.getFormData();

			// 3. remove variable with desired name
			formData.removeVariable(variableName);

			// 4. don't forget to set changed formdata back to folder
			folder.setFormData(formData);

			// 5. save changes and unlock the folder
			folder.save("remove variable", false);
		} finally {
			folder.setLock(false, false);
		}
	}
}

    • getPageGroups

      PageGroup[] getPageGroups()
      Get the list of the page-groups for the current PageReference
      Returns:
      list of the page-groups objects
      Since:
      3.0

    • createPageGroup

      PageGroup createPageGroup(String name)
      Create a new page-group for the current PageReference. It's necessary to call StoreElement.save(String, boolean) on this folder afterwards
      Parameters:
      name - name of the new page-group
      Returns:
      new page-group as object
      Since:
      3.0

    • deletePageGroup

      void deletePageGroup(PageGroup pageGroup)
      Delete the given page-group for the current PageReference
      Parameters:
      pageGroup - page-group to be deleted
      Since:
      3.0

    • getStoredUrl

      @Nullable @Nullable String getStoredUrl(@NotNull @NotNull Language language, @NotNull @NotNull TemplateSet templateSet)
      Get the stored URL for this node and the provided combination of language and template set.
      Parameters:
      language - Language to get the URL for.
      templateSet - TemplateSet to get the URL for.
      Returns:
      The stored URL (absolute, without domain prefix) or null if no URL has been stored (yet).
      Throws:
      NullPointerException - if either parameter language or templateSet is null.
      Since:
      5.0.4
      See Also: