SoftwareInfoForm.java

  1. /**
  2.  *
  3.  * Copyright 2020 Aditya Borikar, 2021 Florian Schmaus
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.jivesoftware.smackx.softwareinfo.form;

  18. import java.util.List;

  19. import org.jivesoftware.smack.util.EqualsUtil;
  20. import org.jivesoftware.smack.util.HashCode;
  21. import org.jivesoftware.smackx.formtypes.FormFieldRegistry;
  22. import org.jivesoftware.smackx.mediaelement.element.MediaElement;
  23. import org.jivesoftware.smackx.xdata.FormField;
  24. import org.jivesoftware.smackx.xdata.FormFieldChildElement;
  25. import org.jivesoftware.smackx.xdata.TextSingleFormField;
  26. import org.jivesoftware.smackx.xdata.form.FilledForm;
  27. import org.jivesoftware.smackx.xdata.form.Form;
  28. import org.jivesoftware.smackx.xdata.packet.DataForm;

  29. /**
  30.  * {@link Form} that contains the software information.
  31.  * <br>
  32.  * Instance of {@link SoftwareInfoForm} can be created using {@link Builder#build()} method.
  33.  * <br>
  34.  * To obtain an instance of {@link Builder}, use {@link SoftwareInfoForm#getBuilder()} method.
  35.  * <br>
  36.  * An example to illustrate is provided inside SoftwareInfoFormTest inside the test package.
  37.  */
  38. public final class SoftwareInfoForm extends FilledForm {

  39.     public static final String FORM_TYPE = "urn:xmpp:dataforms:softwareinfo";
  40.     public static final String OS = "os";
  41.     public static final String OS_VERSION = "os_version";
  42.     public static final String SOFTWARE = "software";
  43.     public static final String SOFTWARE_VERSION = "software_version";
  44.     public static final String ICON = "icon";

  45.     static {
  46.         FormFieldRegistry.register(FORM_TYPE, FormField.Type.text_single,
  47.                         OS, OS_VERSION, SOFTWARE, SOFTWARE_VERSION);
  48.     }

  49.     private SoftwareInfoForm(DataForm dataForm) {
  50.         super(dataForm);
  51.     }

  52.     /**
  53.      * Returns name of the OS used by client.
  54.      * <br>
  55.      * @return os
  56.      */
  57.     public String getOS() {
  58.         return readFirstValue(OS);
  59.     }

  60.     /**
  61.      * Returns version of the OS used by client.
  62.      * <br>
  63.      * @return os_version
  64.      */
  65.     public String getOSVersion() {
  66.         return readFirstValue(OS_VERSION);
  67.     }

  68.     /**
  69.      * Returns name of the software used by client.
  70.      * <br>
  71.      * @return software
  72.      */
  73.     public String getSoftwareName() {
  74.         return readFirstValue(SOFTWARE);
  75.     }

  76.     /**
  77.      * Returns version of the software used by client.
  78.      * <br>
  79.      * @return software_version
  80.      */
  81.     public String getSoftwareVersion () {
  82.         return readFirstValue(SOFTWARE_VERSION);
  83.     }

  84.     /**
  85.      * Returns the software icon if used by client.
  86.      * <br>
  87.      * @return {@link MediaElement} MediaElement or null
  88.      */
  89.     public MediaElement getIcon () {
  90.         FormField field = getField(ICON);
  91.         if (field == null) {
  92.             return null;
  93.         }
  94.         FormFieldChildElement media = field.getFormFieldChildElement(MediaElement.QNAME);
  95.         if (media == null) {
  96.             return null;
  97.         }
  98.         return (MediaElement) media;
  99.     }

  100.     @Override
  101.     public boolean equals(Object obj) {
  102.         return EqualsUtil.equals(this, obj, (equalsBuilder, otherObj) -> {
  103.             equalsBuilder.append(getDataForm().getType(), otherObj.getDataForm().getType())
  104.                          .append(getDataForm().getTitle(), otherObj.getDataForm().getTitle())
  105.                          .append(getDataForm().getReportedData(), otherObj.getDataForm().getReportedData())
  106.                          .append(getDataForm().getItems(), otherObj.getDataForm().getItems())
  107.                          .append(getDataForm().getFields(), otherObj.getDataForm().getFields())
  108.                          .append(getDataForm().getExtensionElements(), otherObj.getDataForm().getExtensionElements());
  109.         });
  110.     }

  111.     @Override
  112.     public int hashCode() {
  113.         HashCode.Builder builder = HashCode.builder();
  114.         builder.append(getDataForm().getFields());
  115.         builder.append(getDataForm().getItems());
  116.         builder.append(getDataForm().getExtensionElements());
  117.         return builder.build();
  118.     }

  119.     /**
  120.      * Returns a new instance of {@link Builder}.
  121.      * <br>
  122.      * @return Builder
  123.      */
  124.     public static Builder getBuilder() {
  125.         return new Builder();
  126.     }

  127.     /**
  128.      * Builder class for {@link SoftwareInfoForm}.
  129.      * <br>
  130.      * To obtain an instance of {@link Builder}, use {@link SoftwareInfoForm#getBuilder()} method.
  131.      * <br>
  132.      * Use appropriate setters to include information inside SoftwareInfoForms.
  133.      */
  134.     public static final class Builder {
  135.         DataForm.Builder dataFormBuilder;

  136.         private Builder() {
  137.             dataFormBuilder = DataForm.builder(DataForm.Type.result);
  138.             TextSingleFormField formField = FormField.buildHiddenFormType(FORM_TYPE);
  139.             dataFormBuilder.addField(formField);
  140.         }

  141.         /**
  142.          * This will allow to include Icon using height, width and Uri's as a
  143.          * {@link FormField}.
  144.          * <br>
  145.          * @param height  Height of the image
  146.          * @param width   Width of the image
  147.          * @param uriList List of URIs
  148.          * @return Builder
  149.          */
  150.         public Builder setIcon(int height, int width, List<MediaElement.Uri> uriList) {
  151.             MediaElement.Builder mediaBuilder = MediaElement.builder();
  152.             for (MediaElement.Uri uri : uriList) {
  153.                 mediaBuilder.addUri(uri);
  154.             }
  155.             MediaElement mediaElement = mediaBuilder.setHeightAndWidth(height, width).build();
  156.             return setIcon(mediaElement);
  157.         }

  158.         /**
  159.          * This will allow to include {@link MediaElement} directly as a
  160.          * {@link FormField}.
  161.          * <br>
  162.          * @param mediaElement MediaElement to be included
  163.          * @return Builder
  164.          */
  165.         public Builder setIcon(MediaElement mediaElement) {
  166.             FormField.Builder<?, ?> builder = FormField.builder(ICON);
  167.             builder.addFormFieldChildElement(mediaElement);
  168.             dataFormBuilder.addField(builder.build());
  169.             return this;
  170.         }

  171.         /**
  172.          * Include Operating System's name as a {@link FormField}.
  173.          * <br>
  174.          * @param os Name of the OS
  175.          * @return Builder
  176.          */
  177.         public Builder setOS(String os) {
  178.             TextSingleFormField.Builder builder = FormField.builder(OS);
  179.             builder.setValue(os);
  180.             dataFormBuilder.addField(builder.build());
  181.             return this;
  182.         }

  183.         /**
  184.          * Include Operating System's version as a {@link FormField}.
  185.          * <br>
  186.          * @param os_version Version of OS
  187.          * @return Builder
  188.          */
  189.         public Builder setOSVersion(String os_version) {
  190.             TextSingleFormField.Builder builder = FormField.builder(OS_VERSION);
  191.             builder.setValue(os_version);
  192.             dataFormBuilder.addField(builder.build());
  193.             return this;
  194.         }

  195.         /**
  196.          * Include Software name as a {@link FormField}.
  197.          * <br>
  198.          * @param software Name of the software
  199.          * @return Builder
  200.          */
  201.         public Builder setSoftware(String software) {
  202.             TextSingleFormField.Builder builder = FormField.builder(SOFTWARE);
  203.             builder.setValue(software);
  204.             dataFormBuilder.addField(builder.build());
  205.             return this;
  206.         }

  207.         /**
  208.          * Include Software Version as a {@link FormField}.
  209.          * <br>
  210.          * @param softwareVersion Version of the Software in use
  211.          * @return Builder
  212.          */
  213.         public Builder setSoftwareVersion(String softwareVersion) {
  214.             TextSingleFormField.Builder builder = FormField.builder(SOFTWARE_VERSION);
  215.             builder.setValue(softwareVersion);
  216.             dataFormBuilder.addField(builder.build());
  217.             return this;
  218.         }

  219.         /**
  220.          * Include {@link DataForm} to be encapsulated under SoftwareInfoForm.
  221.          * <br>
  222.          * @param dataForm The dataform containing Software Information
  223.          * @return Builder
  224.          */
  225.         public Builder setDataForm(DataForm dataForm) {
  226.             if (dataForm.getTitle() != null || !dataForm.getItems().isEmpty()
  227.                     || dataForm.getReportedData() != null || !dataForm.getInstructions().isEmpty()) {
  228.                 throw new IllegalArgumentException("Illegal Arguements for SoftwareInformation");
  229.             }
  230.             String formTypeValue = dataForm.getFormType();
  231.             if (formTypeValue == null) {
  232.                 throw new IllegalArgumentException("FORM_TYPE Formfield missing");
  233.             }
  234.             if (!formTypeValue.equals(SoftwareInfoForm.FORM_TYPE)) {
  235.                 throw new IllegalArgumentException("Malformed FORM_TYPE Formfield encountered");
  236.             }
  237.             this.dataFormBuilder = dataForm.asBuilder();
  238.             return this;
  239.         }

  240.         /**
  241.          * This method is called to build a {@link SoftwareInfoForm}.
  242.          * <br>
  243.          * @return Builder
  244.          */
  245.         public SoftwareInfoForm build() {
  246.             return new SoftwareInfoForm(dataFormBuilder.build());
  247.         }
  248.     }
  249. }